diff options
Diffstat (limited to 'files/zh-tw/web/api')
292 files changed, 50362 insertions, 0 deletions
diff --git a/files/zh-tw/web/api/abortcontroller/index.html b/files/zh-tw/web/api/abortcontroller/index.html new file mode 100644 index 0000000000..8caa750806 --- /dev/null +++ b/files/zh-tw/web/api/abortcontroller/index.html @@ -0,0 +1,97 @@ +--- +title: AbortController +slug: Web/API/AbortController +translation_of: Web/API/AbortController +--- +<div>{{APIRef("DOM")}}{{SeeCompatTable}}</div> + +<p><strong><code>AbortController</code></strong> 介面代表一個控制器物件，讓你可以在需要時中斷一個或多個 DOM 請求。</p> + +<p>你可以使用 {{domxref("AbortController.AbortController()")}} 建立一個新的 <code>AbortController</code> 物件。與 DOM 請求溝通時則是使用 {{domxref("AbortSignal")}} 物件。</p> + +<h2 id="建構子">建構子</h2> + +<dl> + <dt>{{domxref("AbortController.AbortController()")}}</dt> + <dd>建立一個新的 <code>AbortController</code> 物件實體。</dd> +</dl> + +<h2 id="屬性">屬性</h2> + +<dl> + <dt>{{domxref("AbortController.signal")}} {{readonlyInline}}</dt> + <dd>回傳一個 {{domxref("AbortSignal")}} 物件實體，可以用來中斷一個 DOM 請求、或是與其溝通。</dd> +</dl> + +<h2 id="方法">方法</h2> + +<dl> + <dt>{{domxref("AbortController.abort()")}}</dt> + <dd>在一個 DOM 請求完成前中斷他。這可以用來中斷 <a href="/zh-TW/docs/Web/API/WindowOrWorkerGlobalScope/fetch">fetch 請求</a>、對任何 Response {{domxref("Body")}} 的讀取、或是資料流。</dd> +</dl> + +<h2 id="範例">範例</h2> + +<p>在下面的程式碼片段中，我們要用 <a href="/zh-TW/docs/Web/API/Fetch_API">Fetch API</a> 來下載一部影片。</p> + +<p>我們首先用 {{domxref("AbortController.AbortController","AbortController()")}} 建立一個控制器，然後透過 {{domxref("AbortController.signal")}} 屬性取得他的 {{domxref("AbortSignal")}} 物件。</p> + +<p>在初始化 <a href="/en-TW/docs/Web/API/WindowOrWorkerGlobalScope/fetch">fetch 請求</a> 的時候，我們把 <code>AbortSignal</code> 作為選項傳入該請求的選項物件中（參考下方的 <code>{signal}</code>）。這樣會把剛才的中斷訊號與控制器跟 fetch 請求關聯起來，讓我們可以透過呼叫 {{domxref("AbortController.abort()")}} 來中斷該請求。請參考下方範例中第二個事件處理器。</p> + +<pre class="brush: js">var controller = new AbortController(); +var signal = controller.signal; + +var downloadBtn = document.querySelector('.download'); +var abortBtn = document.querySelector('.abort'); + +downloadBtn.addEventListener('click', fetchVideo); + +abortBtn.addEventListener('click', function() { + controller.abort(); + console.log('下載已中斷'); +}); + +function fetchVideo() { + ... + fetch(url, {signal}).then(function(response) { + ... + }).catch(function(e) { + reports.textContent = '下載錯誤: ' + e.message; + }) +}</pre> + +<div class="note"> +<p><strong>注意</strong>: 當 <code>abort()</code> 被呼叫的時候，<code>fetch()</code> 回傳的 Promise 會被以 <code>AbortError</code> 拒絕。</p> +</div> + +<p>在 GitHub 有個完整的範例可供參考 — 請參見 <a href="https://github.com/mdn/dom-examples/tree/master/abort-api">abort-api</a>（<a href="https://mdn.github.io/dom-examples/abort-api/">或是也可以實際體驗看看</a>）。</p> + +<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('DOM WHATWG', '#interface-abortcontroller', 'AbortController')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>初始定義</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + + + +<p>{{Compat("api.AbortController")}}</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/zh-TW/docs/Web/API/Fetch_API">Fetch API</a></li> + <li><a href="https://developers.google.com/web/updates/2017/09/abortable-fetch">Abortable Fetch</a> by Jake Archibald</li> +</ul> diff --git a/files/zh-tw/web/api/ambient_light_events/index.html b/files/zh-tw/web/api/ambient_light_events/index.html new file mode 100644 index 0000000000..06eadc5621 --- /dev/null +++ b/files/zh-tw/web/api/ambient_light_events/index.html @@ -0,0 +1,96 @@ +--- +title: 使用光線事件 +slug: Web/API/Ambient_Light_Events +translation_of: Web/API/Ambient_Light_Events +--- +<p>{{ SeeCompatTable }}</p> +<h2 id="摘要">摘要</h2> +<p>環境光源 (Ambient light) 事件，可告知 Apps 或網頁目前光線強度的變化，以利做出反應，例如改變使用者介面 (User Interface，UI) 的顏色對比，或在拍照時改變曝光程度</p> +<h2 id="光源事件">光源事件</h2> +<p>只要裝置的光線感測器偵測到光線強度變化，隨即通知瀏覽器。一旦瀏覽器取得該通知，就會發出 <a href="https://developer.mozilla.org/en-US/docs/DOM/DeviceLightEvent" title="/en-US/docs/DOM/DeviceLightEvent"><code>DeviceLightEvent</code></a> 事件而提供光線強度的確實資訊。</p> +<p>只要使用 <a href="https://developer.mozilla.org/en-US/docs/DOM/EventTarget.addEventListener" title="/en-US/docs/DOM/EventTarget.addEventListener"><code>addEventListener</code></a> 函式 (使用 {{event("devicelight")}} 事件名稱)，或將事件處理器 (Event Handler) 附加至 <a href="https://developer.mozilla.org/en-US/docs/DOM/window.ondevicelight" title="/en-US/docs/DOM/window.ondevicelight"><code>window.ondevicelight</code></a> 屬性，均可於 <code>window</code> 物件擷取到此事件。</p> +<p>一旦擷取完畢，則事件物件將透過 <a href="https://developer.mozilla.org/en-US/docs/DOM/DeviceLightEvent.value" title="/en-US/docs/DOM/DeviceLightEvent.value"><code>DeviceLightEvent.value</code></a> 屬性，存取光線強度值 (以 <a href="http://en.wikipedia.org/wiki/Lux" title="http://en.wikipedia.org/wiki/Lux">Lux</a> 為單位)。</p> +<h2 id="範例">範例</h2> +<pre class="brush: js">window.addEventListener('devicelight', function(event) { + var html = document.getElementsByTagName('html')[0]; + + if (event.value < 50) { + html.classList.add('darklight'); + html.classList.remove('brightlight'); + } else { + html.classList.add('brightlight'); + html.classList.remove('darklight'); + } +});</pre> +<h2 id="Specifications" name="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('AmbientLight', '', 'Ambient Light Events') }}</td> + <td>{{ Spec2('AmbientLight') }}</td> + <td>Initial specification</td> + </tr> + </tbody> +</table> +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> +<p>{{ CompatibilityTable() }}</p> +<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>{{domxref("DeviceLightEvent")}}</td> + <td>{{CompatNo()}}</td> + <td>{{CompatGeckoDesktop("22.0")}} (Mac OS X only)</td> + <td>{{CompatNo()}}</td> + <td>{{CompatNo()}}</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>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>{{domxref("DeviceLightEvent")}}</td> + <td>{{CompatNo()}}</td> + <td>{{CompatNo()}}</td> + <td>{{CompatGeckoMobile("15.0")}}</td> + <td>{{CompatNo()}}</td> + <td>{{CompatNo()}}</td> + <td>{{CompatNo()}}</td> + </tr> + </tbody> + </table> +</div> +<h3 id="Gecko_說明">Gecko 說明</h3> +<p><code>已建構 </code>{{event("devicelight")}} 事件，且在 Firefox Mobile for Android (15.0) 與 Firefox OS (B2G) 中均預設為開啟。從 Gecko 22.0 (Firefox 22.0 / Thunderbird 22.0 / SeaMonkey 2.19) 開始，亦提供 Mac OS X 的桌機支援。目前對 Windows 7 的支援功能仍開發中 (請見 <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=754199">bug 754199</a>)。</p> +<h2 id="另請參閱">另請參閱</h2> +<ul> + <li>{{domxref("DeviceLightEvent")}}</li> + <li>{{event("devicelight")}}</li> +</ul> diff --git a/files/zh-tw/web/api/analysernode/getbytefrequencydata/index.html b/files/zh-tw/web/api/analysernode/getbytefrequencydata/index.html new file mode 100644 index 0000000000..d6b226dd8f --- /dev/null +++ b/files/zh-tw/web/api/analysernode/getbytefrequencydata/index.html @@ -0,0 +1,149 @@ +--- +title: AnalyserNode.getByteFrequencyData() +slug: Web/API/AnalyserNode/getByteFrequencyData +translation_of: Web/API/AnalyserNode/getByteFrequencyData +--- +<p>{{ APIRef("Web Audio API") }}</p> + +<div> +<p>{{ domxref("AnalyserNode") }} 介面的 <strong><code>getByteFrequencyData()</code></strong> 方法會將當前的頻率資料複製到 {{domxref("Uint8Array")}} （無號 byte 陣列）。</p> + +<p>如果陣列的元素數目比 {{domxref("AnalyserNode.frequencyBinCount")}} 少的話，多餘的元素會被 drop 掉。如果比需要的少的話，多餘的元素會被忽略。</p> +</div> + +<h2 id="語法">語法</h2> + +<pre class="brush: js">var audioCtx = new AudioContext(); +var analyser = audioCtx.createAnalyser(); +var dataArray = new Uint8Array(analyser.frequencyBinCount); // Uint8Array 應該要和 frequencyBinCount 等長 +analyser.getByteFrequencyData(dataArray); // 將 getByteFrequencyData() 回傳的資料放進 Uint8Array +</pre> + +<h3 id="回傳值">回傳值</h3> + +<p>{{domxref("Uint8Array")}}。</p> + +<h2 id="範例">範例</h2> + +<p>下面的範例顯示出 {{domxref("AudioContext")}} 用於建立一個 <code>AnalyserNode</code> 的基本用法，然後 {{domxref("window.requestAnimationFrame()", "requestAnimationFrame")}} 以及 {{htmlelement("canvas")}} 用來重複收集當前聲音輸入的頻率資料並在 "winamp bargraph style" 畫出輸出。若要知道更完整的範例或是資訊，請參考 <a href="http://mdn.github.io/voice-change-o-matic/">Voice-change-O-matic</a> demo （看 <a href="https://github.com/mdn/voice-change-o-matic/blob/gh-pages/scripts/app.js#L128-L205">app.js 第 128–205 行</a> 會有相關的程式碼）。</p> + +<pre class="brush: js">var audioCtx = new (window.AudioContext || window.webkitAudioContext)(); +var analyser = audioCtx.createAnalyser(); + + ... + +analyser.fftSize = 256; +var bufferLength = analyser.frequencyBinCount; +console.log(bufferLength); +var dataArray = new Uint8Array(bufferLength); + +canvasCtx.clearRect(0, 0, WIDTH, HEIGHT); + +function draw() { + drawVisual = requestAnimationFrame(draw); + + analyser.getByteFrequencyData(dataArray); + + canvasCtx.fillStyle = 'rgb(0, 0, 0)'; + canvasCtx.fillRect(0, 0, WIDTH, HEIGHT); + + var barWidth = (WIDTH / bufferLength) * 2.5; + var barHeight; + var x = 0; + + for(var i = 0; i < bufferLength; i++) { + barHeight = dataArray[i]; + + canvasCtx.fillStyle = 'rgb(' + (barHeight+100) + ',50,50)'; + canvasCtx.fillRect(x,HEIGHT-barHeight/2,barWidth,barHeight/2); + + x += barWidth + 1; + } +}; + +draw();</pre> + +<h2 id="參數">參數</h2> + +<dl> + <dt>陣列</dt> + <dd>頻率定義域會被複製進去的 {{domxref("Uint8Array")}} 。</dd> +</dl> + +<h2 id="規範">規範</h2> + +<table class="standard-table" style="height: 105px; width: 593px;"> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">Comment</th> + </tr> + <tr> + <td>{{SpecName('Web Audio API', '#widl-AnalyserNode-getByteFrequencyData-void-Uint8Array-array', 'getByteFrequencyData()')}}</td> + <td>{{Spec2('Web Audio API')}}</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatChrome(10.0)}}{{property_prefix("webkit")}}</td> + <td>{{CompatGeckoDesktop(25.0)}} </td> + <td>{{CompatNo}}</td> + <td>15.0{{property_prefix("webkit")}}<br> + 22 (unprefixed)</td> + <td>6.0{{property_prefix("webkit")}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS</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>{{CompatUnknown}}</td> + <td>26.0</td> + <td>1.2</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>33.0</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="參看">參看</h2> + +<ul> + <li><a href="/en-US/docs/Web_Audio_API/Using_Web_Audio_API">使用 Web Audio API</a></li> +</ul> diff --git a/files/zh-tw/web/api/analysernode/index.html b/files/zh-tw/web/api/analysernode/index.html new file mode 100644 index 0000000000..875993cea9 --- /dev/null +++ b/files/zh-tw/web/api/analysernode/index.html @@ -0,0 +1,226 @@ +--- +title: AnalyserNode +slug: Web/API/AnalyserNode +tags: + - API + - AnalyserNode + - Interface + - NeedsTranslation + - Reference + - TopicStub + - Web Audio API +translation_of: Web/API/AnalyserNode +--- +<p>{{APIRef("Web Audio API")}}</p> + +<p>The <strong><code>AnalyserNode</code></strong><strong> </strong>interface represents a node able to provide real-time frequency and time-domain analysis information. It is an {{domxref("AudioNode")}} that passes the audio stream unchanged from the input to the output, but allows you to take the generated data, process it, and create audio visualizations.</p> + +<p>An <code>AnalyzerNode</code> has exactly one input and one output. The node works even if the output is not connected.</p> + +<p><img alt="Without modifying the audio stream, the node allows to get the frequency and time-domain data associated to it, using a FFT." src="https://mdn.mozillademos.org/files/9707/WebAudioFFT.png" style="height: 174px; width: 661px;"></p> + +<table class="properties"> + <tbody> + <tr> + <th scope="row">Number of inputs</th> + <td><code>1</code></td> + </tr> + <tr> + <th scope="row">Number of outputs</th> + <td><code>1</code> (but may be left unconnected)</td> + </tr> + <tr> + <th scope="row">Channel count mode</th> + <td><code>"explicit"</code></td> + </tr> + <tr> + <th scope="row">Channel count</th> + <td><code>1</code></td> + </tr> + <tr> + <th scope="row">Channel interpretation</th> + <td><code>"speakers"</code></td> + </tr> + </tbody> +</table> + +<h2 id="Inheritance">Inheritance</h2> + +<p>This interface inherits from the following parent interfaces:</p> + +<p>{{InheritanceDiagram}}</p> + +<h2 id="Properties">Properties</h2> + +<p><em>Inherits properties from its parent, </em><em>{{domxref("AudioNode")}}</em>.</p> + +<dl> + <dt>{{domxref("AnalyserNode.fftSize")}}</dt> + <dd>Is an unsigned long value representing the size of the FFT (<a href="http://en.wikipedia.org/wiki/Fast_Fourier_transform" title="/en-US/docs/">Fast Fourier Transform</a>) to be used to determine the frequency domain.</dd> + <dt>{{domxref("AnalyserNode.frequencyBinCount")}} {{readonlyInline}}</dt> + <dd>Is an unsigned long value half that of the FFT size. This generally equates to the number of data values you will have to play with for the visualization.</dd> + <dt>{{domxref("AnalyserNode.minDecibels")}}</dt> + <dd>Is a double value representing the minimum power value in the scaling range for the FFT analysis data, for conversion to unsigned byte values — basically, this specifies the minimum value for the range of results when using <code>getByteFrequencyData()</code>.</dd> + <dt>{{domxref("AnalyserNode.maxDecibels")}}</dt> + <dd>Is a double value representing the maximum power value in the scaling range for the FFT analysis data, for conversion to unsigned byte values — basically, this specifies the maximum value for the range of results when using <code>getByteFrequencyData()</code>.</dd> + <dt>{{domxref("AnalyserNode.smoothingTimeConstant")}}</dt> + <dd>Is a double value representing the averaging constant with the last analysis frame — basically, it makes the transition between values over time smoother.</dd> +</dl> + +<h2 id="Methods">Methods</h2> + +<p><em>Inherits methods from its parent, </em><em>{{domxref("AudioNode")}}</em>.</p> + +<dl> + <dt>{{domxref("AnalyserNode.getFloatFrequencyData()")}}</dt> + <dd>Copies the current frequency data into a {{domxref("Float32Array")}} array passed into it.</dd> +</dl> + +<dl> + <dt>{{domxref("AnalyserNode.getByteFrequencyData()")}}</dt> + <dd>Copies the current frequency data into a {{domxref("Uint8Array")}} (unsigned byte array) passed into it.</dd> +</dl> + +<dl> + <dt>{{domxref("AnalyserNode.getFloatTimeDomainData()")}}</dt> + <dd>Copies the current waveform, or time-domain, data into a {{domxref("Float32Array")}} array passed into it.</dd> + <dt>{{domxref("AnalyserNode.getByteTimeDomainData()")}}</dt> + <dd>Copies the current waveform, or time-domain, data into a {{domxref("Uint8Array")}} (unsigned byte array) passed into it.</dd> +</dl> + +<h2 id="Examples">Examples</h2> + +<div class="note"> +<p><strong>Note</strong>: See the guide <a href="/en-US/docs/Web/API/Web_Audio_API/Visualizations_with_Web_Audio_API">Visualizations with Web Audio API</a> for more information on creating audio visualizations.</p> +</div> + +<h3 id="Basic_usage">Basic usage</h3> + +<p>The following example shows basic usage of an {{domxref("AudioContext")}} to create an <code>AnalyserNode</code>, then {{domxref("window.requestAnimationFrame()","requestAnimationFrame")}} and {{htmlelement("canvas")}} to collect time domain data repeatedly and draw an "oscilloscope style" output of the current audio input. For more complete applied examples/information, check out our <a href="http://mdn.github.io/voice-change-o-matic/">Voice-change-O-matic</a> demo (see <a href="https://github.com/mdn/voice-change-o-matic/blob/gh-pages/scripts/app.js#L128-L205">app.js lines 128–205</a> for relevant code).</p> + +<pre class="brush: js">var audioCtx = new (window.AudioContext || window.webkitAudioContext)(); +var analyser = audioCtx.createAnalyser(); + + ... + +analyser.fftSize = 2048; +var bufferLength = analyser.frequencyBinCount; +var dataArray = new Uint8Array(bufferLength); +analyser.getByteTimeDomainData(dataArray); + +// draw an oscilloscope of the current audio source + +function draw() { + + drawVisual = requestAnimationFrame(draw); + + analyser.getByteTimeDomainData(dataArray); + + canvasCtx.fillStyle = 'rgb(200, 200, 200)'; + canvasCtx.fillRect(0, 0, WIDTH, HEIGHT); + + canvasCtx.lineWidth = 2; + canvasCtx.strokeStyle = 'rgb(0, 0, 0)'; + + canvasCtx.beginPath(); + + var sliceWidth = WIDTH * 1.0 / bufferLength; + var x = 0; + + for(var i = 0; i < bufferLength; i++) { + + var v = dataArray[i] / 128.0; + var y = v * HEIGHT/2; + + if(i === 0) { + canvasCtx.moveTo(x, y); + } else { + canvasCtx.lineTo(x, y); + } + + x += sliceWidth; + } + + canvasCtx.lineTo(canvas.width, canvas.height/2); + canvasCtx.stroke(); + }; + + draw();</pre> + +<h2 id="Specifications">Specifications</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('Web Audio API', '#the-analysernode-interface', 'AnalyserNode')}}</td> + <td>{{Spec2('Web Audio API')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatChrome(10.0)}}{{property_prefix("webkit")}}</td> + <td>{{CompatGeckoDesktop(25.0)}} </td> + <td>{{CompatNo}}</td> + <td>15.0 {{property_prefix("webkit")}}<br> + 22</td> + <td>6.0{{property_prefix("webkit")}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS</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>{{CompatUnknown}}</td> + <td>26.0</td> + <td>1.2</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>33.0</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/Web_Audio_API/Using_Web_Audio_API">Using the Web Audio API</a></li> +</ul> diff --git a/files/zh-tw/web/api/animationevent/index.html b/files/zh-tw/web/api/animationevent/index.html new file mode 100644 index 0000000000..d4528894b5 --- /dev/null +++ b/files/zh-tw/web/api/animationevent/index.html @@ -0,0 +1,182 @@ +--- +title: AnimationEvent +slug: Web/API/AnimationEvent +tags: + - API + - CSS + - CSS Animations + - Experimental + - Interface + - NeedsTranslation + - Reference + - TopicStub +translation_of: Web/API/AnimationEvent +--- +<p>{{SeeCompatTable}}{{APIRef("Web Animations API")}}</p> + +<h2 id="摘要">摘要</h2> + +<p><strong><code>AnimationEvent</code></strong> 介面表現提供<a href="/zh-TW/docs/Web/Guide/CSS/Using_CSS_animations">動畫</a>相關資訊的事件。</p> + +<p>{{InheritanceDiagram}}</p> + +<h2 id="性能">性能</h2> + +<p><em>另外從其父 {{domxref("Event")}} 繼承屬性</em>。</p> + +<dl> + <dt>{{domxref("AnimationEvent.animationName")}} {{readonlyInline}}</dt> + <dd>是一個{{domxref("DOMString")}}包含的值 {{cssxref("animation-name")}} CSS屬性與過渡有關。</dd> + <dt>{{domxref("AnimationEvent.elapsedTime")}} {{readonlyInline}}</dt> + <dd>是一個<code>float</code>給予時間的動畫已經運行，以秒為單位，當該事件燒製，不含動畫被暫停的任何時間量。為一個<code>"animationstart"</code>事件，<code>elapsedTime</code>是<code>0.0</code>，除非有一個負值{{cssxref("animation-delay")}}，在這種情況下，該事件將與燒製<code>elapsedTime</code>含有 <code>(-1 * </code><em>delay</em><code>)</code>。</dd> + <dt>{{domxref("AnimationEvent.pseudoElement")}} {{readonlyInline}}</dt> + <dd>是一個{{domxref("DOMString")}}，從<code>"::"</code>，包含的名字<a href="/zh-TW/docs/Web/CSS/Pseudo-elements">虛擬元素</a>的動畫運行。如果動畫上不偽元素，但該元素，一個空字符串上運行<code>：''。</code></dd> +</dl> + +<h2 id="構造函數">構造函數</h2> + +<dl> + <dt>{{domxref("AnimationEvent.AnimationEvent","AnimationEvent()")}}</dt> + <dd>創建一個<code>AnimationEvent</code>事件具有給定參數。</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>同時繼承其父{{domxref("事件")}}方法</em>。</p> + +<dl> + <dt>{{domxref("AnimationEvent.initAnimationEvent()")}} {{non-standard_inline}}{{deprecated_inline}}</dt> + <dd>初始化<code>AnimationEvent</code> 使用過時的創建 {{domxref("Document.createEvent()", "Document.createEvent(\"AnimationEvent\")")}} 方法。</dd> +</dl> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">產品規格</th> + <th scope="col">狀態</th> + <th scope="col">註解</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{ SpecName('CSS3 Animations', '#AnimationEvent-interface', 'AnimationEvent') }}</td> + <td>{{ Spec2('CSS3 Animations') }}</td> + <td>初始定義。</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器兼容性">瀏覽器兼容性</h2> + +<p>{{CompatibilityTable()}}</p> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>特點</th> + <th>Chrome</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>基本支持</td> + <td>1.0 {{ property_prefix("webkit") }}</td> + <td>{{CompatGeckoDesktop("6.0")}}</td> + <td>10.0</td> + <td>12 {{property_prefix("O")}}<br> + 12.10<br> + 15.0 {{ property_prefix("webkit") }}</td> + <td>4.0 {{ property_prefix("webkit") }}</td> + </tr> + <tr> + <td><code>AnimationEvent()</code>構造函數</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop("23.0")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>initAnimationEvent()</code>{{non-standard_inline}} {{deprecated_inline}}</td> + <td>1.0</td> + <td>{{CompatGeckoDesktop("6.0")}}<br> + 在{{CompatGeckoDesktop("23.0")}}刪除</td> + <td>10.0</td> + <td>12</td> + <td>4</td> + </tr> + <tr> + <td><code>pseudoelement</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop("23.0")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>特點</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + <th>Chrome for Android</th> + </tr> + <tr> + <td>基本支持</td> + <td>{{CompatVersionUnknown}}{{ property_prefix("webkit") }}</td> + <td>{{ CompatGeckoMobile("6.0") }}</td> + <td>10.0</td> + <td>12 {{ property_prefix("o") }}<br> + 12.10<br> + 15.0 {{ property_prefix("webkit") }}</td> + <td>{{CompatVersionUnknown}}{{ property_prefix("webkit") }}</td> + <td>{{CompatChrome(43.0)}}</td> + </tr> + <tr> + <td><code>AnimationEvent()</code>構造函數</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile("23.0")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>initAnimationEvent()</code>{{non-standard_inline}} {{deprecated_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("6.0")}}<br> + 在{{CompatGeckoMobile("23.0")}}刪除</td> + <td>10.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>pseudoelement</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile("23.0")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="另請參見">另請參見</h2> + +<ul> + <li><a href="/zh-TW/docs/CSS/Using_CSS_animations">使用CSS動畫</a></li> + <li>Animation-related CSS properties and at-rules: {{cssxref("animation")}}, {{cssxref("animation-delay")}}, {{cssxref("animation-direction")}}, {{cssxref("animation-duration")}}, {{cssxref("animation-fill-mode")}}, {{cssxref("animation-iteration-count")}}, {{cssxref("animation-name")}}, {{cssxref("animation-play-state")}}, {{cssxref("animation-timing-function")}}, {{cssxref("@keyframes")}}.</li> +</ul> diff --git a/files/zh-tw/web/api/animationevent/initanimationevent/index.html b/files/zh-tw/web/api/animationevent/initanimationevent/index.html new file mode 100644 index 0000000000..de5c7efe15 --- /dev/null +++ b/files/zh-tw/web/api/animationevent/initanimationevent/index.html @@ -0,0 +1,129 @@ +--- +title: AnimationEvent.initAnimationEvent() +slug: Web/API/AnimationEvent/initAnimationEvent +tags: + - API + - AnimationEvent + - CSSOM + - Method + - Obsolete + - Web Animations +translation_of: Web/API/AnimationEvent/initAnimationEvent +--- +<p>{{obsolete_header}}{{non-standard_header}}{{ apiref("Web Animations API") }}</p> + +<h2 id="Summary">Summary</h2> + +<p>The <code><strong>AnimationEvent.initAnimationEvent()</strong></code> method Initializes an animation event created using the deprecated {{domxref("Document.createEvent()", "Document.createEvent(\"AnimationEvent\")")}} method.</p> + +<p><code>AnimationEvent</code> created this way are untrusted.</p> + +<div class="note"> +<p><strong>Note:</strong> During the standardization process, this method was removed from the specification. It has been deprecated and is in the progress of being removed from most implementations. <strong>Do not use this method</strong>; instead, use the standard constructor, {{domxref("AnimationEvent.AnimationEvent", "AnimationEvent()")}}, to create a synthetic {{domxref("AnimationEvent")}}.</p> +</div> + +<h2 id="Syntax">Syntax</h2> + +<pre class="syntaxbox"><em>animationEvent</em>.initAnimationEvent(<em>typeArg</em>, <em>canBubbleArg</em>, <em>cancelableArg</em>, <em>animationNameArg</em>, <em>elapsedTimeArg</em>);</pre> + +<h3 id="Parameters">Parameters</h3> + +<dl> + <dt><code>typeArg</code></dt> + <dd>A {{domxref("DOMString")}} identifying the specific type of animation event that occurred. The following values are allowed: + <table class="standard-table"> + <thead> + <tr> + <th scope="col">Value</th> + <th scope="col">Meaning</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>animationstart</code></td> + <td>The animation has started.</td> + </tr> + <tr> + <td><code>animationend</code></td> + <td>The animation completed.</td> + </tr> + <tr> + <td><code>animationiteration</code></td> + <td>The current iteration just completed.</td> + </tr> + </tbody> + </table> + </dd> + <dt><code>canBubbleArg</code></dt> + <dd>A {{domxref("Boolean")}} flag indicating if the event can bubble (<code>true</code>) or not (<code>false)</code>.</dd> + <dt><code>cancelableArg</code></dt> + <dd>A {{domxref("Boolean")}} flag indicating if the event associated action can be avoided (<code>true</code>) or not (<code>false)</code>.</dd> + <dt><code>animationNameArg</code></dt> + <dd>A {{domxref("DOMString")}} containing the value of the {{cssxref("animation-name")}} CSS property associated with the transition.</dd> + <dt><code>elapsedTimeArg</code></dt> + <dd>A <code>float</code> indicating the amount of time the animation has been running, in seconds, as of the time the event was fired, excluding any time the animation was paused. For an <code>"animationstart"</code> event, <code>elapsedTime</code> is <code>0.0</code> unless there was a negative value for <code><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/animation-delay" title="The animation-delay CSS property specifies when the animation should start. This lets the animation sequence begin some time after it's applied to an element.">animation-delay</a></code>, in which case the event will be fired with <code>elapsedTime</code> containing <code>(-1 * </code><em>delay</em><code>)</code>.</dd> +</dl> + +<h2 id="Specifications">Specifications</h2> + +<p><em>This method is non-standard and not part of any specification, though it was present in early drafts of {{SpecName("CSS3 Animations")}}.</em></p> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{ CompatibilityTable }}</p> + +<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>{{CompatVersionUnknown}}</td> + <td>{{ CompatGeckoDesktop("6.0") }}<br> + Removed in {{ CompatGeckoDesktop("23.0") }}</td> + <td>10.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{ CompatGeckoMobile("6.0") }}<br> + Removed in {{ CompatGeckoMobile("23.0") }}</td> + <td>10.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="https://developer.mozilla.org/en-US/docs/CSS/Using_CSS_animations">Using CSS animations</a></li> + <li>Animation-related CSS properties and at-rules: {{cssxref("animation")}}, {{cssxref("animation-delay")}}, {{cssxref("animation-direction")}}, {{cssxref("animation-duration")}}, {{cssxref("animation-fill-mode")}}, {{cssxref("animation-iteration-count")}}, {{cssxref("animation-name")}}, {{cssxref("animation-play-state")}}, {{cssxref("animation-timing-function")}}, {{cssxref("@keyframes")}}.</li> + <li>The {{domxref("AnimationEvent")}} interface it belongs to.</li> +</ul> diff --git a/files/zh-tw/web/api/battery_status_api/index.html b/files/zh-tw/web/api/battery_status_api/index.html new file mode 100644 index 0000000000..cbf98d417d --- /dev/null +++ b/files/zh-tw/web/api/battery_status_api/index.html @@ -0,0 +1,38 @@ +--- +title: Battery Status API +slug: Web/API/Battery_Status_API +translation_of: Web/API/Battery_Status_API +--- +<p><strong>Battery Status API</strong> 也就是所謂的 <strong>Battery API</strong>，將提供系統電池充電容量的資訊，並在電池容量變化時送出事件，以通知使用者。此 API 可調整 Apps 的資源耗用量，在電力偏低時縮減耗電量；或可在電力耗盡之前儲存檔案，避免資料遺失。</p> +<p>Battery Status API 是以 <a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.battery" title="/en-US/docs/Web/API/window.navigator.battery"><code>window.navigator.battery</code></a> 屬性 (為 <a href="https://developer.mozilla.org/en-US/docs/Web/API/BatteryManager" title="/en-US/docs/Web/API/BatteryManager"><code>BatteryManager</code></a> 物件) 而擴充了 <a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator" title="/en-US/docs/Web/API/window.navigator"><code>window.navigator</code></a>，並新增數項可讓使用者接收的新事件，以隨時監控電池狀態。</p> +<h2 id="範例">範例</h2> +<p>在此範例中，我們將分別監聽 <a href="https://developer.mozilla.org/en-US/docs/Web/Reference/Events/chargingchange" title="/en-US/docs/Web/Reference/Events/chargingchange">chargingchange</a> 與 <a href="https://developer.mozilla.org/en-US/docs/Web/Reference/Events/levelchange" title="/en-US/docs/Web/Reference/Events/levelchange">levelchange</a> 事件，而看到充電狀態 (不論是否插電進行充電) 與電池容量的變化。</p> +<pre class="brush: js">var battery = navigator.battery || navigator.mozBattery || navigator.webkitBattery; + +function updateBatteryStatus() { + console.log("Battery status: " + battery.level * 100 + " %"); + + if (battery.charging) { + console.log("Battery is charging"); + } +} + +battery.addEventListener("chargingchange", updateBatteryStatus); +battery.addEventListener("levelchange", updateBatteryStatus); +updateBatteryStatus(); +</pre> +<p>另可參閱<a href="http://dev.w3.org/2009/dap/system-info/battery-status.html#introduction">規格所提供之範例</a>。</p> +<h2 id="規格">規格</h2> +<p>{{page("/en-US/docs/Web/API/BatteryManager","Specifications")}}</p> +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> +<p>{{page("/en-US/docs/Web/API/BatteryManager","Browser_compatibility")}}</p> +<h2 id="另請參閱">另請參閱</h2> +<ul> + <li><a href="http://hacks.mozilla.org/2012/02/using-the-battery-api-part-of-webapi/">部落格文章 - Using the Battery API</a></li> + <li><a href="http://davidwalsh.name/battery-api" title="http://davidwalsh.name/battery-api">David Walsh 所寫的 JavaScript Battery Api</a></li> + <li><a href="https://github.com/pstadler/battery.js" title="https://github.com/pstadler/battery.js">battery.js - 跨瀏覽器 wrapper</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/BatteryManager" title="/en-US/docs/Web/API/BatteryManager"><code>BatteryManager</code></a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.battery" title="/en-US/docs/Web/API/window.navigator.battery"><code>navigator.battery</code></a></li> + <li><code><a href="http://tools.guyellisrocks.com/experiment/batterystatus" title="http://tools.guyellisrocks.com/experiment/batterystatus">測試你的瀏覽器是否支援 Battery Status API</a>。可掃 QR Code:</code></li> + <li> <a href="http://x.co/qr/batstat?s=165"><img alt="QR Code to Battery Status API Test Page" src="http://x.co/qr/batstat?s=165" style="width: 165px; height: 165px;"></a></li> +</ul> diff --git a/files/zh-tw/web/api/blob/blob/index.html b/files/zh-tw/web/api/blob/blob/index.html new file mode 100644 index 0000000000..26fb1e8ef7 --- /dev/null +++ b/files/zh-tw/web/api/blob/blob/index.html @@ -0,0 +1,125 @@ +--- +title: Blob() +slug: Web/API/Blob/Blob +translation_of: Web/API/Blob/Blob +--- +<p>{{APIRef("File API")}}</p> + +<p><code><strong>Blob()</strong></code> 建構式會回傳一個新建立的 {{domxref("Blob")}} 物件。新物件的內容是由 <em>array</em> 參數的成員值串連所構成。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">var aBlob = new Blob(<em> array</em>, <em>options</em> ); +</pre> + +<h3 id="參數">參數</h3> + +<ul> + <li><em>array</em> 可以是一個由 {{jsxref("ArrayBuffer")}}、{{domxref("ArrayBufferView")}}、{{domxref("Blob")}} 或 {{domxref("DOMString")}} 組成的 {{jsxref("Array")}} 物件，或是上述多種型別物件的混合陣列。這個陣列將會被放進新建立的 <code>Blob</code> 物件當中。DOMStrings 的編碼為 UTF-8。</li> + <li><em>option</em><em>s</em> 是選擇性的 <code>BlobPropertyBag</code> 字典物件，有以下兩個指定的屬性： + <ul> + <li><code>type</code> 屬性，預設值為空字串 <code>""</code>，表示將被放進 <code>Blob</code> 物件的陣列內容之 MIME 類型。</li> + <li><code>endings</code> 屬性，表示包含 <code>\n</code> 換行字元的字串要如何輸出，預設值為字串 <code>"transparent"</code>。此屬性值可為：<code>"native"</code>，代表換行字元會被轉為目前作業系統的換行字元編碼。也可以是 <code>"transparent"</code>，代表保留 <code>Blob</code> 物件中資料的換行字元。{{non-standard_inline}}</li> + </ul> + </li> +</ul> + +<h2 id="範例">範例</h2> + +<pre class="brush: js language-js">var aFileParts = ['<a id="a"><b id="b">hey!</b></a>']; // an array consisting of a single DOMString +var oMyBlob = new Blob(aFileParts, {type : 'text/html'}); // the blob</pre> + +<h2 id="Specification" name="Specification">規範</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('File API', '#constructorBlob', 'Blob()')}}</td> + <td>{{Spec2('File API')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>功能</th> + <th>Chrome</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td> + <p>基礎支援</p> + </td> + <td>20</td> + <td>{{CompatGeckoDesktop("13.0")}} [1]</td> + <td>10</td> + <td>12.10</td> + <td>8</td> + </tr> + <tr> + <td>在 Workers 中</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoDesktop("14.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>功能</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>基礎支援</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("13.0")}} [1]</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>在 Workers 中</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("14.0")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] 在 Firefox 16 以前，第二個參數若被設為 <code>null</code> 或 <code>undefined</code> 會導致錯誤而不是當成一個空鍵值。</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>廢棄的 {{domxref("BlobBuilder")}} 和取代他的建構子。</li> +</ul> + +<p> </p> diff --git a/files/zh-tw/web/api/blob/index.html b/files/zh-tw/web/api/blob/index.html new file mode 100644 index 0000000000..457628556c --- /dev/null +++ b/files/zh-tw/web/api/blob/index.html @@ -0,0 +1,116 @@ +--- +title: Blob +slug: Web/API/Blob +translation_of: Web/API/Blob +--- +<p>{{APIRef("File API")}}</p> + +<p><code>Blob</code>（Binary Large Object）物件代表了一個相當於檔案（原始資料）的不可變物件。Blob 中的資料並不一定是 JavaScript 原生的格式。{{domxref("File")}} 介面基於 <code>Blob，</code>繼承 blob 並擴充其功能以支援操作使用者系統上的檔案。</p> + +<p>從其它非 Blob 物件或資料來建構 <code>Blob</code> 物件，可以使用 {{domxref("Blob.Blob", "Blob()")}} 建構式。要建立一個包含目前 blob 內容子集的 blob，可使用 {{domxref("Blob.slice()", "slice()")}} 方法。若要自使用者系統上的檔案取得 <code>Blob</code> 物件，請參考 {{domxref("File")}} 文件。</p> + +<p>接受 Blob 物件的 API 可以在 {{domxref("File")}} 上找到。</p> + +<div class="note"> +<p><strong>註：</strong>早期 <code>slice()</code> 方法擁有第二個參數 <code>length</code> 以指定在建立新 <code>Blob</code> 物件時要複製的位元組（byte）數量。假如指定的 <code>start + length</code> 超出了來源 <code>Blob</code> 的大小，則回傳的 <code>Blob</code> 會包含自索引 <code>start</code> 至結尾的完整來源內容。</p> +</div> + +<div class="note"> +<p><strong>註：</strong>需注意在部分瀏覽器版本中，<code>slice()</code> 方法帶有前綴：Firefox 12 與之前的版本為 <code>blob.mozSlice()</code>，Safari 中是 <code>blob.webkitSlice()</code>。舊的、無前綴字版本的 <code>slice()</code> 方法則有不同的語意（semantics），但這是已淘汰的方法。瀏覽器對 <code>blob.mozSlice()</code> 的支援已在 Firefox 30 時中止。</p> +</div> + +<h2 id="建構式">建構式</h2> + +<dl> + <dt>{{domxref("Blob.Blob", "Blob(blobParts[, options])")}}</dt> + <dd>回傳新建立的 <code>Blob</code> 物件，包含了建構式參數傳入之陣列所串聯後的值。第二個參數為 <font face="Consolas, Liberation Mono, Courier, monospace">BlobPropertyBag</font> <font face="Consolas, Liberation Mono, Courier, monospace">物件，其擁有</font> <code>type</code> 和 <code>endings</code> 屬性<font face="Consolas, Liberation Mono, Courier, monospace">。</font></dd> +</dl> + +<h2 id="屬性">屬性</h2> + +<dl> + <dt>{{domxref("Blob.size")}} {{readonlyinline}}</dt> + <dd>以 byte 為單位的 <code>Blob</code> 物件大小。</dd> + <dt>{{domxref("Blob.type")}} {{readonlyinline}}</dt> + <dd><code>Blob</code> 物件中資料的型態，以 MIME 類型的字串表示。若型態為未知，則為空字串。</dd> +</dl> + +<h2 id="方法">方法</h2> + +<dl> + <dt>{{domxref("Blob.slice()", "Blob.slice([start[, end[, contentType]]])")}}</dt> + <dd>回傳一個包含當前 <code>Blob</code> 物件之指定資料範圍（byte）內容的新 <code>Blob</code> 物件。</dd> +</dl> + +<h2 id="範例">範例</h2> + +<h3 id="Blob_建構函數用法範例">Blob 建構函數用法範例</h3> + +<p>{{domxref("Blob.Blob", "Blob() constructor")}} 建構式允許由其它物件建立 blob 物件。以下的範例演示了以字串來建構 blob 物件：</p> + +<pre class="brush: js">var debug = {hello: "world"}; +var blob = new Blob([JSON.stringify(debug, null, 2)], {type : 'application/json'});</pre> + +<div class="warning"> +<p>在 Blob 建構式出現之前，可以透過 {{domxref("BlobBuilder")}} 來建立 blob 物件（目前已不建議使用）：</p> + +<pre class="brush: js">var builder = new BlobBuilder(); +var fileParts = ['<a id="a"><b id="b">hey!</b></a>']; +builder.append(fileParts[0]); +var myBlob = builder.getBlob('text/xml');</pre> +</div> + +<h3 id="藉型別陣列建構的_blob_來建立_URL">藉型別陣列建構的 blob 來建立 URL</h3> + +<p>範例程式碼：</p> + +<pre class="brush: js">var typedArray = GetTheTypedArraySomehow(); +var blob = new Blob([typedArray], {type: 'application/octet-binary'}); // pass a useful mime type here +var url = URL.createObjectURL(blob); +// url will be something like: blob:d3958f5c-0777-0845-9dcf-2cb28783acaf +// now you can use the url in any context that regular URLs can be used in, for example img.src, etc. +</pre> + +<h3 id="從_Blob_取出資料">從 Blob 取出資料</h3> + +<p>從 Blob 讀取資料的唯一方式就是使用 {{domxref("FileReader")}}。以下範例展示了讀取 Blob 內容作為型別陣列：</p> + +<pre class="brush: js">var reader = new FileReader(); +reader.addEventListener("loadend", function() { + // reader.result contains the contents of blob as a typed array +}); +reader.readAsArrayBuffer(blob);</pre> + +<p>藉由操作 {{domxref("FileReader")}} 的其他方法，將 Blob 讀取成字串或是 data URL 是有可能的。</p> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">註解</th> + </tr> + <tr> + <td>{{SpecName('File API','#blob','Blob')}}</td> + <td>{{Spec2('File API')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + + + +<p>{{Compat("api.Blob")}}</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("BlobBuilder")}}</li> + <li>{{domxref("File")}}</li> + <li>{{domxref("URL.createObjectURL")}}</li> + <li><a href="/en-US/docs/Components.utils.importGlobalProperties">Components.utils.importGlobalProperties</a></li> +</ul> diff --git a/files/zh-tw/web/api/blob/size/index.html b/files/zh-tw/web/api/blob/size/index.html new file mode 100644 index 0000000000..0abccad27d --- /dev/null +++ b/files/zh-tw/web/api/blob/size/index.html @@ -0,0 +1,114 @@ +--- +title: Blob.size +slug: Web/API/Blob/size +tags: + - API + - Files + - Property + - Reference + - WebAPI + - 參考 + - 屬性 +translation_of: Web/API/Blob/size +--- +<div>{{APIRef("File API")}}</div> + +<p><strong><code>Blob.size</code></strong> 屬性回傳以 byte 為單位的 {{domxref("Blob")}} 或一個 {{domxref("File")}} 的大小。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">var sizeInBytes = <em>blob</em>.size +</pre> + +<h2 id="值">值</h2> + +<p>一個數字。</p> + +<h2 id="範例">範例</h2> + +<pre class="brush:js">// fileInput 是個 HTMLInputElement: <input type="file" multiple id="myfileinput"> +var fileInput = document.getElementById("myfileinput"); + +// files 是個 FileList 物件 （類似 NodeList） +var files = fileInput.files; + +for (var i = 0; i < files.length; i++) { + console.log(files[i].name + " has a size of " + files[i].size + " Bytes"); +}</pre> + +<h2 id="規格">規格</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規格</th> + <th scope="col">狀態</th> + <th scope="col">附註</th> + </tr> + <tr> + <td>{{SpecName('File API', '#dfn-size', 'size')}}</td> + <td>{{Spec2('File API')}}</td> + <td>初定義</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<div>{{CompatibilityTable}}</div> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>功能</th> + <th>Chrome</th> + <th>Edge</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari (WebKit)</th> + </tr> + <tr> + <td>File.size</td> + <td>5</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("2")}}</td> + <td>10.0</td> + <td>11.10</td> + <td>5.1</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>功能</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>File.size</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("Blob")}}</li> +</ul> diff --git a/files/zh-tw/web/api/blob/type/index.html b/files/zh-tw/web/api/blob/type/index.html new file mode 100644 index 0000000000..ee2a231724 --- /dev/null +++ b/files/zh-tw/web/api/blob/type/index.html @@ -0,0 +1,114 @@ +--- +title: Blob.type +slug: Web/API/Blob/type +translation_of: Web/API/Blob/type +--- +<div>{{APIRef("File API")}}</div> + +<p><a href="/en-US/docs/Web/API/Blob"><code>Blob</code></a> 物件的 <strong><code>type</code></strong> 屬性提供檔案的 <a href="https://developer.mozilla.org/zh-TW/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Complete_list_of_MIME_types">MIME 類別</a>。若無法辨明型別則回傳空字串。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">var mimetype = <var>instanceOfFile</var>.type</pre> + +<h2 id="值">值</h2> + +<p>一個字串。</p> + +<h2 id="範例">範例</h2> + +<pre class="brush:js">var i, fileInput, files, allowedFileTypes; + +// fileInput 是個 HTMLInputElement: <input type="file" multiple id="myfileinput"> +fileInput = document.getElementById("myfileinput"); + +// files 是個 FileList 物件 （類似 NodeList） +files = fileInput.files; + +// 這範例接受 *.png, *.jpeg 和 *.gif 圖片。 +allowedFileTypes = ["image/png", "image/jpeg", "image/gif"]; + +for (i = 0; i < files.length; i++) { + // 測試 file.type 是否是允許的類別。 + if (allowedFileTypes.indexOf(<strong>files[i].type</strong>) > -1) { + // 若符合則執行這裡的程式碼。 + } +}); +</pre> + +<h2 id="規格">規格</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規格</th> + <th scope="col">狀態</th> + <th scope="col">備註</th> + </tr> + <tr> + <td>{{SpecName('File API', '#dfn-type', 'type')}}</td> + <td>{{Spec2('File API')}}</td> + <td>初定義</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<div>{{CompatibilityTable}}</div> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>功能</th> + <th>Chrome</th> + <th>Edge</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari (WebKit)</th> + </tr> + <tr> + <td>File.type</td> + <td>5</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("2")}}</td> + <td>10.0</td> + <td>11.10</td> + <td>5.1</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>功能</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>File.type</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("Blob")}}</li> +</ul> diff --git a/files/zh-tw/web/api/body/index.html b/files/zh-tw/web/api/body/index.html new file mode 100644 index 0000000000..82ba54e53d --- /dev/null +++ b/files/zh-tw/web/api/body/index.html @@ -0,0 +1,99 @@ +--- +title: Body +slug: Web/API/Body +tags: + - API + - BODY + - Experimental + - Fetch + - Fetch API + - Interface + - NeedsTranslation + - Reference + - TopicStub + - request +translation_of: Web/API/Body +--- +<div>{{ APIRef("Fetch") }}</div> + +<p><span class="seoSummary">The <strong><code>Body</code></strong> {{glossary("mixin")}} of the <a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a> represents the body of the response/request, allowing you to declare what its content type is and how it should be handled.</span></p> + +<p><code>Body</code> is implemented by both {{domxref("Request")}} and {{domxref("Response")}}. This provides these objects with an associated <dfn>body</dfn> (a <a href="/en-US/docs/Web/API/Streams_API">stream</a>), a <dfn>used flag</dfn> (initially unset), and a <dfn>MIME type</dfn> (initially the empty byte sequence).</p> + +<h2 id="Properties">Properties</h2> + +<dl> + <dt>{{domxref("Body.body")}} {{readonlyInline}}</dt> + <dd>A simple getter used to expose a {{domxref("ReadableStream")}} of the body contents.</dd> + <dt>{{domxref("Body.bodyUsed")}} {{readonlyInline}}</dt> + <dd>A {{domxref("Boolean")}} that indicates whether the body has been read.</dd> +</dl> + +<h2 id="Methods">Methods</h2> + +<dl> + <dt>{{domxref("Body.arrayBuffer()")}}</dt> + <dd>Takes a {{domxref("Response")}} stream and reads it to completion. It returns a promise that resolves with an {{domxref("ArrayBuffer")}}.</dd> + <dt>{{domxref("Body.blob()")}}</dt> + <dd>Takes a {{domxref("Response")}} stream and reads it to completion. It returns a promise that resolves with a {{domxref("Blob")}}.</dd> + <dt>{{domxref("Body.formData()")}}</dt> + <dd>Takes a {{domxref("Response")}} stream and reads it to completion. It returns a promise that resolves with a {{domxref("FormData")}} object.</dd> + <dt>{{domxref("Body.json()")}}</dt> + <dd>Takes a {{domxref("Response")}} stream and reads it to completion. It returns a promise that resolves with the result of parsing the body text as {{jsxref("JSON")}}.</dd> + <dt>{{domxref("Body.text()")}}</dt> + <dd>Takes a {{domxref("Response")}} stream and reads it to completion. It returns a promise that resolves with a {{domxref("USVString")}} (text). The response is <em>always</em> decoded using UTF-8.</dd> +</dl> + +<h2 id="Examples">Examples</h2> + +<p>The example below uses a simple fetch call to grab an image and display it in an {{htmlelement("img")}} tag. You'll notice that since we are requesting an image, we need to run {{domxref("Body.blob","Body.blob()")}} ({{domxref("Response")}} implements body) to give the response its correct MIME type.</p> + +<h3 id="HTML_Content">HTML Content</h3> + +<pre class="brush: html"><img class="my-image" src="https://wikipedia.org/static/images/project-logos/frwiki-1.5x.png"> +</pre> + +<h3 id="JS_Content">JS Content</h3> + +<pre class="brush: js">var myImage = document.querySelector('.my-image'); +fetch('https://upload.wikimedia.org/wikipedia/commons/7/77/Delete_key1.jpg') + .then(res => res.blob()) + .then(res => { + var objectURL = URL.createObjectURL(res); + myImage.src = objectURL; +});</pre> + +<p>{{ EmbedLiveSample('Examples', '100%', '250px') }}</p> + +<h2 id="Specifications">Specifications</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('Fetch','#body-mixin','Body')}}</td> + <td>{{Spec2('Fetch')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + + + +<p>{{Compat("api.Body")}}</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/ServiceWorker_API">ServiceWorker API</a></li> + <li><a href="/en-US/docs/Web/HTTP/Access_control_CORS">HTTP access control (CORS)</a></li> + <li><a href="/en-US/docs/Web/HTTP">HTTP</a></li> +</ul> + +<p> </p> diff --git a/files/zh-tw/web/api/body/json/index.html b/files/zh-tw/web/api/body/json/index.html new file mode 100644 index 0000000000..70085afff7 --- /dev/null +++ b/files/zh-tw/web/api/body/json/index.html @@ -0,0 +1,73 @@ +--- +title: Body.json() +slug: Web/API/Body/json +translation_of: Web/API/Body/json +--- +<div>{{APIRef("Fetch")}}</div> + +<p>{{domxref("Body")}} mixin 的 <strong><code>json()</code></strong> 會拿 {{domxref("Response")}} stream 並完整地讀取他。它會回傳一個能夠實現 (resolve) 把回傳的結果的 body text 解析成 {{jsxref("JSON")}} 型別的 Promise。</p> + +<h2 id="語法">語法</h2> + +<pre class="brush: js notranslate">response.json().then(function(data) { + // do something with your data +});</pre> + +<h3 id="參數">參數</h3> + +<p>None.</p> + +<h3 id="回傳">回傳</h3> + +<p>一個能夠實現 (resolve) 把回傳的結果的 body text 解析成 JSON 型別的 Promise。這可以是任何能夠被 JSON 呈現的資料型別 — 物件 (object), 陣列 (array), 字串 (string), 數字 (number)...</p> + +<h2 id="範例">範例</h2> + +<p>在我們的範例 <a href="https://github.com/mdn/fetch-examples/tree/master/fetch-json">fetch json example</a> (run <a href="http://mdn.github.io/fetch-examples/fetch-json/">fetch json live</a>) 中，我們用 constructor {{domxref("Request.Request")}} 產生一個新的請求，並且用它去取回 <code>.json</code> 檔案。 當成功取回 (fetch) 時，我們使用 <code>json()</code> 去讀取跟解析資料，然後依照我們期待的把回傳的結果物件 (resulting objects) 裡讀取到的數值存入 list 中藉以顯示我們的產品資料。</p> + +<pre class="brush: js notranslate">var myList = document.querySelector('ul'); + +var myRequest = new Request('products.json'); + +fetch(myRequest) + .then(function(response) { return response.json(); }) + .then(function(data) { + for (var i = 0; i < data.products.length; i++) { + var listItem = document.createElement('li'); + listItem.innerHTML = '<strong>' + data.products[i].Name + '</strong> can be found in ' + + data.products[i].Location + + '. Cost: <strong>£' + data.products[i].Price + '</strong>'; + myList.appendChild(listItem); + } + });</pre> + +<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('Fetch','#dom-body-json','json()')}}</td> + <td>{{Spec2('Fetch')}}</td> + <td></td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + + + +<p>{{Compat("api.Body.json")}}</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/ServiceWorker_API">ServiceWorker API</a></li> + <li><a href="/en-US/docs/Web/HTTP/Access_control_CORS">HTTP access control (CORS)</a></li> + <li><a href="/en-US/docs/Web/HTTP">HTTP</a></li> +</ul> diff --git a/files/zh-tw/web/api/canvas_api/drawing_graphics_with_canvas/index.html b/files/zh-tw/web/api/canvas_api/drawing_graphics_with_canvas/index.html new file mode 100644 index 0000000000..c93ad87e10 --- /dev/null +++ b/files/zh-tw/web/api/canvas_api/drawing_graphics_with_canvas/index.html @@ -0,0 +1,161 @@ +--- +title: Drawing graphics with canvas +slug: Web/API/Canvas_API/Drawing_graphics_with_canvas +translation_of: Web/API/Canvas_API/Tutorial +--- +<div class="note"> + <p>Most of this content (but not the documentation on drawWindow) has been rolled into the more expansive <a href="/en-US/docs/HTML/Canvas/Tutorial" title="HTML/Canvas/tutorial">Canvas tutorial</a>, this page should probably be redirected there as it's now redundant but some information may still be relevant.</p> +</div> +<h2 id="Introduction" name="Introduction">介紹</h2> +<p> 在 <a href="/en-US/docs/Mozilla/Firefox/Releases/1.5" title="Firefox_1.5_for_developers">Firefox 1.5</a>, Firefox 引入了新的 HTML 元素 <canvas> 來繪製圖形。<code><canvas></code> 是基於 <a href="http://www.whatwg.org/specs/web-apps/current-work/#the-canvas">WHATWG canvas specification</a> 的技術 (其發軔於蘋果公司在 Safari 上的實做)。 我們可以用它來在使用者端進行圖形和 UI 元件的渲染。</p> +<p><code> <canvas></code> 創建了一個具有一致多個 <em>rendering contexts 的</em>區域。在本文中，我們著重於 2D rendering context 的部份。對於 3D 圖形，您可以參考 <a href="/en-US/docs/WebGL" title="https://developer.mozilla.org/en/WebGL">WebGL rendering context</a>。</p> +<h2 id="The_2D_Rendering_Context" name="The_2D_Rendering_Context">2D Rendering Context</h2> +<h3 id="A_Simple_Example" name="A_Simple_Example">先來個簡單的範例</h3> +<p> 以下的程式碼做了一個簡單的展示：繪製兩個部份交疊的矩形 (其中一個矩形有透明屬性) :</p> +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + + ctx.fillStyle = "rgb(200,0,0)"; + ctx.fillRect (10, 10, 55, 50); + + ctx.fillStyle = "rgba(0, 0, 200, 0.5)"; + ctx.fillRect (30, 30, 55, 50); +} +</pre> +<div class="hidden"> + <pre class="brush: html"><canvas id="canvas" width="120" height="120"></canvas></pre> + <pre class="brush: js">draw();</pre> +</div> +<p>{{EmbedLiveSample('A_Simple_Example','150','150','/@api/deki/files/602/=Canvas_ex1.png')}}</p> +<p> 這個名為 <code>draw</code> 的函式從 <code>canvas</code> element 取得 <code>2d</code> context。物件 <code>ctx</code> 可以被用來在 canvas 上頭繪製圖形。從程式碼可以看出，我們簡單的藉由設定 fillStyle 繪製了兩個顏色不同的矩形，並透過 <code>fillRect 設定其位置。此外，第二個矩形透過</code> <code>rgba()</code> 配置了透明屬性。</p> +<p> 關於更複雜的圖形繪製，我們可以使用 <code>fillRect</code>, <code>strokeRect 和</code> <code>clearRect，他們分別可以畫出填滿的矩形, 僅有外框的矩形以及矩形區域清除。</code></p> +<h3 id="Using_Paths" name="Using_Paths">路徑的使用</h3> +<p> <code>beginPath</code> 函式用來初始一段路徑的繪製，並且可以透過 <code>moveTo</code>, <code>lineTo</code>, <code>arcTo</code>, <code>arc </code>以及相關的函式來描述路徑內容。要結束的時候呼叫 <code>closePath 即可。一旦路徑描述完畢，就可以透過</code> <code>fill</code> 或 <code>stroke</code> 來渲染該路徑在 canvas 上。</p> +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + + ctx.fillStyle = "red"; + + ctx.beginPath(); + ctx.moveTo(30, 30); + ctx.lineTo(150, 150); + // was: ctx.quadraticCurveTo(60, 70, 70, 150); which is wrong. + ctx.bezierCurveTo(60, 70, 60, 70, 70, 150); // <- this is right formula for the image on the right -> + ctx.lineTo(30, 30); + ctx.fill(); +} +</pre> +<div class="hidden"> + <pre class="brush: html"><canvas id="canvas" width="160" height="160"></canvas></pre> + <pre class="brush: js">draw();</pre> +</div> +<p>{{EmbedLiveSample('Using_Paths','190','190','/@api/deki/files/603/=Canvas_ex2.png')}}</p> +<p> 呼叫 <code>fill()</code> 或 <code>stroke()</code> 代表該路徑已經被使用。若要重新進行填滿等動作，則需要重頭創造一次路徑。</p> +<h3 id="Graphics_State" name="Graphics_State">圖像狀態</h3> +<p> <code>fillStyle</code>, <code>strokeStyle</code>, <code>lineWidth 和</code> <code>lineJoin</code> 等屬性是 <em>graphics state 的一部分。關於這些屬性的修改，您可以透過</em> <code>save()</code> 及 <code>restore() 來進行操作。</code></p> +<h3 id="A_More_Complicated_Example" name="A_More_Complicated_Example">一個更為複雜的範例</h3> +<p> 接著我們來看一個稍微複雜一點的範例，它同時引入了路徑, 狀態的修改以及變換矩陣。</p> +<pre class="brush: js">function drawBowtie(ctx, fillStyle) { + + ctx.fillStyle = "rgba(200,200,200,0.3)"; + ctx.fillRect(-30, -30, 60, 60); + + ctx.fillStyle = fillStyle; + ctx.globalAlpha = 1.0; + ctx.beginPath(); + ctx.moveTo(25, 25); + ctx.lineTo(-25, -25); + ctx.lineTo(25, -25); + ctx.lineTo(-25, 25); + ctx.closePath(); + ctx.fill(); +} + +function dot(ctx) { + ctx.save(); + ctx.fillStyle = "black"; + ctx.fillRect(-2, -2, 4, 4); + ctx.restore(); +} + +function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + + // note that all other translates are relative to this one + ctx.translate(45, 45); + + ctx.save(); + //ctx.translate(0, 0); // unnecessary + drawBowtie(ctx, "red"); + dot(ctx); + ctx.restore(); + + ctx.save(); + ctx.translate(85, 0); + ctx.rotate(45 * Math.PI / 180); + drawBowtie(ctx, "green"); + dot(ctx); + ctx.restore(); + + ctx.save(); + ctx.translate(0, 85); + ctx.rotate(135 * Math.PI / 180); + drawBowtie(ctx, "blue"); + dot(ctx); + ctx.restore(); + + ctx.save(); + ctx.translate(85, 85); + ctx.rotate(90 * Math.PI / 180); + drawBowtie(ctx, "yellow"); + dot(ctx); + ctx.restore(); +} +</pre> +<div class="hidden"> + <pre class="brush: html"><canvas id="canvas" width="185" height="185"></canvas></pre> + <pre class="brush: js">draw();</pre> +</div> +<p>{{EmbedLiveSample('A_More_Complicated_Example','215','215','/@api/deki/files/604/=Canvas_ex3.png')}}</p> +<p> 我們自定義了兩個函式： <code>drawBowtie 以及</code> <code>dot，並且個別呼叫了四次。</code>在呼叫他們之前，我們使用了 <code>translate()</code> 和 <code>rotate()</code> 來設定接著要繪製圖形的 transformation matrix，這將改變最終 dot 和 bowtie 的位置。<code>dot</code> 繪製了一個以 <code>(0, 0) 為中心的小黑正方形，而</code> <code>drawBowtie</code> 產生了一個填滿的蝴蝶結樣貌的圖形。</p> +<p> <code>save()</code> 和 <code>restore()</code> 規範了一系列動作的初始和結尾。一個值得注意的地方是，旋轉的動作是基於該圖形當下所在的位置， 所以 <code>translate() -> rotate() -> translate() 的結果會和</code> <code>translate() -> translate() -> rotate()</code> 不同。</p> +<h2 id="Compatibility_With_Apple_.3Ccanvas.3E" name="Compatibility_With_Apple_.3Ccanvas.3E">和 Apple <canvas> 的相容性</h2> +<p>For the most part, <code><canvas></code> is compatible with Apple's and other implementations. There are, however, a few issues to be aware of, described here.</p> +<h3 id="Required_.3C.2Fcanvas.3E_tag" name="Required_.3C.2Fcanvas.3E_tag"><code></canvas></code> tag 是必要的</h3> +<p>In the Apple Safari implementation, <code><canvas></code> is an element implemented in much the same way <code><img></code> is; it does not have an end tag. However, for <code><canvas></code> to have widespread use on the web, some facility for fallback content must be provided. Therefore, Mozilla's implementation has a <em>required</em> end tag.</p> +<p>If fallback content is not needed, a simple <code><canvas id="foo" ...></canvas></code> will be fully compatible with both Safari and Mozilla -- Safari will simply ignore the end tag.</p> +<p>If fallback content is desired, some CSS tricks must be employed to mask the fallback content from Safari (which should render just the canvas), and also to mask the CSS tricks themselves from IE (which should render the fallback content).</p> +<pre>canvas { + font-size: 0.00001px !ie; +}</pre> +<h2 id="Additional_Features" name="Additional_Features">其他特性</h2> +<h3 id="Rendering_Web_Content_Into_A_Canvas" name="Rendering_Web_Content_Into_A_Canvas">藉由 Canvas 渲染網頁內容</h3> +<div class="note"> + This feature is only available for code running with Chrome privileges. It is not allowed in normal HTML pages. <a href="http://mxr.mozilla.org/mozilla/source/content/canvas/src/nsCanvasRenderingContext2D.cpp#2352" title="http://mxr.mozilla.org/mozilla/source/content/canvas/src/nsCanvasRenderingContext2D.cpp#2352">Read why</a>.</div> +<p>Mozilla's <code>canvas</code> is extended with the <a href="/en-US/docs/DOM/CanvasRenderingContext2D#drawWindow()" title="DOM/CanvasRenderingContext2D#drawWindow()"><code>drawWindow()</code></a> method. This method draws a snapshot of the contents of a DOM <code>window</code> into the canvas. For example,</p> +<pre class="brush: js">ctx.drawWindow(window, 0, 0, 100, 200, "rgb(255,255,255)"); +</pre> +<p>would draw the contents of the current window, in the rectangle (0,0,100,200) in pixels relative to the top-left of the viewport, on a white background, into the canvas. By specifying "rgba(255,255,255,0)" as the color, the contents would be drawn with a transparent background (which would be slower).</p> +<p>It is usually a bad idea to use any background other than pure white "rgb(255,255,255)" or transparent, as this is what all browsers do, and many websites expect that transparent parts of their interface will be drawn on white background.</p> +<p>With this method, it is possible to fill a hidden IFRAME with arbitrary content (e.g., CSS-styled HTML text, or SVG) and draw it into a canvas. It will be scaled, rotated and so on according to the current transformation.</p> +<p>Ted Mielczarek's <a href="http://ted.mielczarek.org/code/mozilla/tabpreview/">tab preview</a> extension uses this technique in chrome to provide thumbnails of web pages, and the source is available for reference.</p> +<div class="note"> + <strong>Note:</strong> Using <code>canvas.drawWindow()</code> while handling a document's <code>onload</code> event doesn't work. In Firefox 3.5 or later, you can do this in a handler for the <a href="/en-US/docs/Gecko-Specific_DOM_Events#MozAfterPaint" title="Gecko-Specific DOM Events#MozAfterPaint"><code>MozAfterPaint</code></a> event to successfully draw HTML content into a canvas on page load.</div> +<h2 id="See_also" name="See_also">更多資訊</h2> +<ul> + <li><a href="/en-US/docs/HTML/Canvas" title="HTML/Canvas">Canvas topic page</a></li> + <li><a href="/en-US/docs/Canvas_tutorial" title="Canvas_tutorial">Canvas tutorial</a></li> + <li><a href="http://www.whatwg.org/specs/web-apps/current-work/#the-canvas">WHATWG specification</a></li> + <li><a href="http://developer.apple.com/documentation/AppleApplications/Conceptual/SafariJSProgTopics/Tasks/Canvas.html" title="http://developer.apple.com/documentation/AppleApplications/Conceptual/SafariJSProgTopics/Tasks/Canvas.html">Apple Canvas Documentation</a></li> + <li><a href="http://weblogs.mozillazine.org/roc/archives/2005/05/rendering_web_p.html">Rendering Web Page Thumbnails</a></li> + <li>Some <a href="/en-US/docs/tag/canvas_examples">examples</a>: + <ul> + <li><a href="http://azarask.in/projects/algorithm-ink">Algorithm Ink</a></li> + <li><a href="http://www.tapper-ware.net/canvas3d/">OBJ format 3D Renderer</a></li> + <li><a href="/en-US/docs/A_Basic_RayCaster" title="A_Basic_RayCaster">A Basic RayCaster</a></li> + <li><a href="http://awordlike.textdriven.com/">The Lightweight Visual Thesaurus</a></li> + <li><a href="http://caimansys.com/painter/">Canvas Painter</a></li> + </ul> + </li> + <li><a href="/en-US/docs/tag/canvas">And more...</a></li> +</ul> diff --git a/files/zh-tw/web/api/canvas_api/index.html b/files/zh-tw/web/api/canvas_api/index.html new file mode 100644 index 0000000000..c07ec36738 --- /dev/null +++ b/files/zh-tw/web/api/canvas_api/index.html @@ -0,0 +1,158 @@ +--- +title: Canvas API +slug: Web/API/Canvas_API +translation_of: Web/API/Canvas_API +--- +<div>{{CanvasSidebar}}</div> + +<p class="summary"><strong>{{HTMLElement("canvas")}}</strong> 是 <a href="/zh-TW/docs/HTML" title="HTML">HTML5</a> 的新元素，可透過 Script（通常是 <a href="/zh-TW/docs/JavaScript" title="JavaScript">JavaScript</a>）繪製圖形。例如，可以用來繪圖、合成圖照片、建立動畫、甚至處理即時的影片播放。</p> + +<p>Mozilla 應用程式從 Gecko 1.8（也就是 <a href="/en/Firefox_1.5_for_developers" title="Firefox_1.5_for_developers">Firefox 1.5</a>）起開始支援 <code><canvas></code>。這個元素最初由蘋果 OS X <a class="external" href="http://www.apple.com/macosx/features/dashboard/">Dashboard</a> 和 Safari 引入。Internet Explorer 9 以上版本也有支援<code> <canvas></code>，但較舊的 IE 版本則須嵌入 Google <a class="external" href="http://excanvas.sourceforge.net/">Explorer Canvas</a> 專案中的程式腳本，才能得到有效的支援。Opera 9 也支援 <code><canvas></code>。</p> + +<p><code><canvas></code> 元素通常也被 <a href="/zh-TW/docs/Web/WebGL">WebGL</a> 用來在網頁上顯示使用硬體加速繪製的 3D 圖形。</p> + +<h2 id="範例">範例</h2> + +<p>這則簡單的範例使用了{{domxref("CanvasRenderingContext2D.fillRect()")}}這個方法。</p> + +<h3 id="HTML">HTML</h3> + +<pre class="brush: html"><canvas id="canvas"></canvas> +</pre> + +<h3 id="JavaScript">JavaScript</h3> + +<pre class="brush: js">var canvas = document.getElementById("canvas"); +var ctx = canvas.getContext("2d"); + +ctx.fillStyle = "green"; +ctx.fillRect(10, 10, 100, 100); +</pre> + +<p>Edit the code below and see your changes update live in the canvas:</p> + +<div class="hidden"> +<h6 id="Playable_code">Playable code</h6> + +<pre class="brush: html"><canvas id="canvas" width="400" height="200" class="playable-canvas"></canvas> +<div class="playable-buttons"> + <input id="edit" type="button" value="Edit" /> + <input id="reset" type="button" value="Reset" /> +</div> +<textarea id="code" class="playable-code"> +ctx.fillStyle = "green"; +ctx.fillRect(10, 10, 100, 100);</textarea> +</pre> + +<pre class="brush: js">var canvas = document.getElementById("canvas"); +var ctx = canvas.getContext("2d"); +var textarea = document.getElementById("code"); +var reset = document.getElementById("reset"); +var edit = document.getElementById("edit"); +var code = textarea.value; + +function drawCanvas() { + ctx.clearRect(0, 0, canvas.width, canvas.height); + eval(textarea.value); +} + +reset.addEventListener("click", function() { + textarea.value = code; + drawCanvas(); +}); + +edit.addEventListener("click", function() { + textarea.focus(); +}) + +textarea.addEventListener("input", drawCanvas); +window.addEventListener("load", drawCanvas); +</pre> +</div> + +<p>{{ EmbedLiveSample('Playable_code', 700, 360) }}</p> + +<h2 id="參考">參考</h2> + +<div class="index"> +<ul> + <li>{{domxref("HTMLCanvasElement")}}</li> + <li>{{domxref("CanvasRenderingContext2D")}}</li> + <li>{{domxref("CanvasGradient")}}</li> + <li>{{domxref("CanvasPattern")}}</li> + <li>{{domxref("ImageBitmap")}}</li> + <li>{{domxref("ImageData")}}</li> + <li>{{domxref("TextMetrics")}}</li> + <li>{{domxref("Path2D")}} {{experimental_inline}}</li> +</ul> +</div> + +<p>這些與<code>WebGLRenderingContext</code>有關的標識，皆引用在<a href="/zh-TW/docs/Web/WebGL" title="/zh-TW/docs/Web/WebGL">WebGL</a></p> + +<h2 id="教程指南">教程指南</h2> + +<dl> + <dt><a href="/zh-TW/docs/Web/API/Canvas_API/Tutorial">Canvas tutorial</a></dt> + <dd>這個全部的課程包含 <code><canvas></code> 基礎的使用和高階的應用。</dd> + <dt><a href="/zh-TW/Add-ons/Code_snippets/Canvas">Code snippets: Canvas</a></dt> + <dd>一些延伸的開發功能，包含<code><canvas></code>。</dd> + <dt><a href="/zh-TW/docs/Web/API/Canvas_API/A_basic_ray-caster">Demo: A basic ray-caster</a></dt> + <dd>使用<code><canvas></code>做的光線追蹤(ray-tracing )範例。</dd> + <dt><a href="/zh-TW/docs/Web/API/Canvas_API/Drawing_DOM_objects_into_a_canvas">Drawing DOM objects into a canvas</a></dt> + <dd>如何在 DOM<code><canvas></code>之中，畫個物件。例如 HTML的元素。</dd> + <dt><a href="/zh-TW/docs/Web/API/Canvas_API/Manipulating_video_using_canvas">Manipulating video using canvas</a></dt> + <dd>結合{{HTMLElement("video")}} 和 {{HTMLElement("canvas")}} 去控制影像資料的真實時間</dd> +</dl> + +<h2 id="資源">資源</h2> + +<h3 id="Generic">Generic</h3> + +<ul> + <li><a href="http://joshondesign.com/p/books/canvasdeepdive/title.html">HTML5 Canvas Deep Dive</a></li> + <li><a href="http://bucephalus.org/text/CanvasHandbook/CanvasHandbook.html">Canvas Handbook</a></li> +</ul> + +<h3 id="Libraries">Libraries</h3> + +<ul> + <li><a href="http://fabricjs.com">Fabric.js</a> is an open-source canvas library with SVG parsing capabilities.</li> + <li><a href="https://github.com/ericdrowell/KineticJS">Kinetic.js</a> is an open-source canvas library focused on interactivity for desktop and mobile applications.</li> + <li><a href="http://paperjs.org/">Paper.js</a> is an open source vector graphics scripting framework that runs on top of the HTML5 Canvas.</li> + <li><a href="http://origamijs.com/docs/">Origami.js</a> is an open source lightweight canvas library.</li> + <li><a href="http://libcanvas.github.com/">libCanvas</a> 是一個強大且輕量化的 canvas 框架。</li> + <li><a href="http://processingjs.org">Processing.js</a> 是視覺化程式語言 Processing 的移植版。</li> + <li><a href="https://playcanvas.com/">PlayCanvas</a> is an open source game engine.</li> + <li><a href="http://www.pixijs.com/">Pixi.js</a> is an open source game engine.</li> + <li><a href="http://www.liquidx.net/plotkit/">PlotKit</a> 是一個製作圖表和圖形的函式庫。</li> + <li><a class="link-https" href="https://github.com/jeremyckahn/rekapi">Rekapi</a> 是一個用來控制動畫影格的 Canvas API。</li> + <li><a href="http://senchalabs.github.com/philogl/">PhiloGL</a> 是一個可應用在資料視覺化、遊戲開發的 WebGL 框架。</li> + <li><a href="http://thejit.org/">JavaScript InfoVis Toolkit</a> 可在網頁上建立 2D 的互動式 Canvas 視覺化資料。</li> + <li><a href="http://www.createjs.com/easeljs">EaselJS</a> 是一個自由 / 開放源始碼的函式庫，目的在簡化 canvas 於遊戲與美術的開發難度，類似 Flash API。</li> + <li><a href="http://scrawl.rikweb.org.uk/">Scrawl-canvas</a> is another open-source javascript library for creating and manipulating 2d canvas elements</li> +</ul> + +<h2 id="規範">規範</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', "the-canvas-element.html", "Canvas")}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/zh-TW/docs/Web/WebGL">WebGL</a></li> +</ul> diff --git a/files/zh-tw/web/api/canvas_api/tutorial/advanced_animations/index.html b/files/zh-tw/web/api/canvas_api/tutorial/advanced_animations/index.html new file mode 100644 index 0000000000..caacb185aa --- /dev/null +++ b/files/zh-tw/web/api/canvas_api/tutorial/advanced_animations/index.html @@ -0,0 +1,376 @@ +--- +title: Advanced animations +slug: Web/API/Canvas_API/Tutorial/Advanced_animations +translation_of: Web/API/Canvas_API/Tutorial/Advanced_animations +--- +<div>{{CanvasSidebar}} {{PreviousNext("Web/API/Canvas_API/Tutorial/Basic_animations", "Web/API/Canvas_API/Tutorial/Pixel_manipulation_with_canvas")}}</div> + +<div class="summary"> +<p>在上一章節，我們做了一些<a href="/en-US/docs/Web/API/Canvas_API/Tutorial/Basic_animations">基礎動畫</a>且知道它的移動方式。在這部分我們更仔細的介紹它的動畫效果且並增加一些特效，使它看起來更高級。</p> +</div> + +<h2 id="畫一顆球">畫一顆球</h2> + +<p>在這次的動畫練習中使用球來練習。照著下面的步驟完成 canvas 設定。</p> + +<pre class="brush: html"><canvas id="canvas" width="600" height="300"></canvas> +</pre> + +<p>照常理，先在canvas上需要先畫一顆球。創造一個 <code>ball</code> object，它包含的屬性和<code>draw()</code>的方法，使canvas可以在上面繪圖。</p> + +<pre class="brush: js">var canvas = document.getElementById('canvas'); +var ctx = canvas.getContext('2d'); + +var ball = { + x: 100, + y: 100, + radius: 25, + color: 'blue', + draw: function() { + ctx.beginPath(); + ctx.arc(this.x, this.y, this.radius, 0, Math.PI * 2, true); + ctx.closePath(); + ctx.fillStyle = this.color; + ctx.fill(); + } +}; + +ball.draw();</pre> + +<p>這裡沒什麼特別的，透過{{domxref("CanvasRenderingContext2D.arc()", "arc()")}}的方法，球事實上只是畫下簡單的圓。</p> + +<h2 id="添加速度">添加速度</h2> + +<p>現在有了一顆球，準備添加基礎的動畫像我們從<a href="/en-US/docs/Web/API/Canvas_API/Tutorial/Basic_animations">上章節學到的課程</a>。再次使用{{domxref("window.requestAnimationFrame()")}}控制動畫。添加移動的向量速度使球移動到向量點。對於每個幀(frame)，我們使用{{domxref("CanvasRenderingContext2D.clearRect", "clear", "", 1)}}來清除canvas舊的移動幀(frame)。</p> + +<pre class="brush: js; highlight:[8,9,24,25]">var canvas = document.getElementById('canvas'); +var ctx = canvas.getContext('2d'); +var raf; + +var ball = { + x: 100, + y: 100, + vx: 5, + vy: 2, + radius: 25, + color: 'blue', + draw: function() { + ctx.beginPath(); + ctx.arc(this.x, this.y, this.radius, 0, Math.PI * 2, true); + ctx.closePath(); + ctx.fillStyle = this.color; + ctx.fill(); + } +}; + +function draw() { + ctx.clearRect(0,0, canvas.width, canvas.height); + ball.draw(); + ball.x += ball.vx; + ball.y += ball.vy; + raf = window.requestAnimationFrame(draw); +} + +canvas.addEventListener('mouseover', function(e) { + raf = window.requestAnimationFrame(draw); +}); + +canvas.addEventListener('mouseout', function(e) { + window.cancelAnimationFrame(raf); +}); + +ball.draw(); +</pre> + +<h2 id="邊界">邊界</h2> + +<p>沒有任何邊界碰撞下，球很快就會跑出canvas。這時需要確認球的 <code>x</code> and <code>y</code> 是否超出 canvas 尺寸，若超出則將球的向量顛倒。所以，我們添加了確認條件在<code>draw</code>方法:</p> + +<pre class="brush: js">if (ball.y + ball.vy > canvas.height || ball.y + ball.vy < 0) { + ball.vy = -ball.vy; +} +if (ball.x + ball.vx > canvas.width || ball.x + ball.vx < 0) { + ball.vx = -ball.vx; +}</pre> + +<h3 id="第一個示範">第一個示範</h3> + +<p>讓我們看看，看似很遠的行徑它如何行徑。移動你的滑鼠在canvas，使動畫開始。 </p> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" style="border: 1px solid" width="600" height="300"></canvas></pre> + +<pre class="brush: js">var canvas = document.getElementById('canvas'); +var ctx = canvas.getContext('2d'); +var raf; + +var ball = { + x: 100, + y: 100, + vx: 5, + vy: 2, + radius: 25, + color: 'blue', + draw: function() { + ctx.beginPath(); + ctx.arc(this.x, this.y, this.radius, 0, Math.PI * 2, true); + ctx.closePath(); + ctx.fillStyle = this.color; + ctx.fill(); + } +}; + +function draw() { + ctx.clearRect(0,0, canvas.width, canvas.height); + ball.draw(); + ball.x += ball.vx; + ball.y += ball.vy; + + if (ball.y + ball.vy > canvas.height || + ball.y + ball.vy < 0) { + ball.vy = -ball.vy; + } + if (ball.x + ball.vx > canvas.width || + ball.x + ball.vx < 0) { + ball.vx = -ball.vx; + } + + raf = window.requestAnimationFrame(draw); +} + +canvas.addEventListener('mouseover', function(e) { + raf = window.requestAnimationFrame(draw); +}); + +canvas.addEventListener('mouseout', function(e) { + window.cancelAnimationFrame(raf); +}); + +ball.draw();</pre> +</div> + +<p>{{EmbedLiveSample("First_demo", "610", "310")}}</p> + +<h2 id="加速性能">加速性能</h2> + +<p>為了使移動看起來更真實，你可以照著範例改變速度:</p> + +<pre class="brush: js">ball.vy *= .99; +ball.vy += .25;</pre> + +<p>這個使每個幀(frame)的垂直向量減少，所以球將只會在地板彈跳直到結束。</p> + +<div class="hidden"> +<h6 id="Second_demo">Second demo</h6> + +<pre class="brush: html"><canvas id="canvas" style="border: 1px solid" width="600" height="300"></canvas></pre> + +<pre class="brush: js">var canvas = document.getElementById('canvas'); +var ctx = canvas.getContext('2d'); +var raf; + +var ball = { + x: 100, + y: 100, + vx: 5, + vy: 2, + radius: 25, + color: 'blue', + draw: function() { + ctx.beginPath(); + ctx.arc(this.x, this.y, this.radius, 0, Math.PI * 2, true); + ctx.closePath(); + ctx.fillStyle = this.color; + ctx.fill(); + } +}; + +function draw() { + ctx.clearRect(0,0, canvas.width, canvas.height); + ball.draw(); + ball.x += ball.vx; + ball.y += ball.vy; + ball.vy *= .99; + ball.vy += .25; + + if (ball.y + ball.vy > canvas.height || + ball.y + ball.vy < 0) { + ball.vy = -ball.vy; + } + if (ball.x + ball.vx > canvas.width || + ball.x + ball.vx < 0) { + ball.vx = -ball.vx; + } + + raf = window.requestAnimationFrame(draw); +} + +canvas.addEventListener('mouseover', function(e) { + raf = window.requestAnimationFrame(draw); +}); + +canvas.addEventListener('mouseout', function(e) { + window.cancelAnimationFrame(raf); +}); + +ball.draw();</pre> +</div> + +<p>{{EmbedLiveSample("Second_demo", "610", "310")}}</p> + +<h2 id="追蹤效果">追蹤效果</h2> + +<p>直到現在我們已經使用{{domxref("CanvasRenderingContext2D.clearRect", "clearRect")}}方法清除之前的幀(frames)。如果使用重置半透明{{domxref("CanvasRenderingContext2D.fillRect", "fillRect")}}這個方法，可以更淺顯的看出創造追蹤效果。</p> + +<pre class="brush: js">ctx.fillStyle = 'rgba(255, 255, 255, 0.3)'; +ctx.fillRect(0, 0, canvas.width, canvas.height);</pre> + +<div class="hidden"> +<h6 id="Third_demo">Third demo</h6> + +<pre class="brush: html"><canvas id="canvas" style="border: 1px solid" width="600" height="300"></canvas></pre> + +<pre class="brush: js">var canvas = document.getElementById('canvas'); +var ctx = canvas.getContext('2d'); +var raf; + +var ball = { + x: 100, + y: 100, + vx: 5, + vy: 2, + radius: 25, + color: 'blue', + draw: function() { + ctx.beginPath(); + ctx.arc(this.x, this.y, this.radius, 0, Math.PI * 2, true); + ctx.closePath(); + ctx.fillStyle = this.color; + ctx.fill(); + } +}; + +function draw() { + ctx.fillStyle = 'rgba(255, 255, 255, 0.3)'; + ctx.fillRect(0, 0, canvas.width, canvas.height); + ball.draw(); + ball.x += ball.vx; + ball.y += ball.vy; + ball.vy *= .99; + ball.vy += .25; + + if (ball.y + ball.vy > canvas.height || + ball.y + ball.vy < 0) { + ball.vy = -ball.vy; + } + if (ball.x + ball.vx > canvas.width || + ball.x + ball.vx < 0) { + ball.vx = -ball.vx; + } + + raf = window.requestAnimationFrame(draw); +} + +canvas.addEventListener('mouseover', function(e) { + raf = window.requestAnimationFrame(draw); +}); + +canvas.addEventListener('mouseout', function(e) { + window.cancelAnimationFrame(raf); +}); + +ball.draw();</pre> +</div> + +<p>{{EmbedLiveSample("Third_demo", "610", "310")}}</p> + +<h2 id="增加滑鼠控制">增加滑鼠控制</h2> + +<p>為了能控制球使它跟著滑鼠移動，在這個範例使用<code><a href="/en-US/docs/Web/Reference/Events/mousemove">mousemove</a></code> 效果。當 <code><a href="/en-US/docs/Web/Events/click">click</a></code> 事件觸發了這顆球，它又會開始彈跳。</p> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" style="border: 1px solid" width="600" height="300"></canvas></pre> +</div> + +<pre class="brush: js">var canvas = document.getElementById('canvas'); +var ctx = canvas.getContext('2d'); +var raf; +var running = false; + +var ball = { + x: 100, + y: 100, + vx: 5, + vy: 1, + radius: 25, + color: 'blue', + draw: function() { + ctx.beginPath(); + ctx.arc(this.x, this.y, this.radius, 0, Math.PI * 2, true); + ctx.closePath(); + ctx.fillStyle = this.color; + ctx.fill(); + } +}; + +function clear() { + ctx.fillStyle = 'rgba(255, 255, 255, 0.3)'; + ctx.fillRect(0,0,canvas.width,canvas.height); +} + +function draw() { + clear(); + ball.draw(); + ball.x += ball.vx; + ball.y += ball.vy; + + if (ball.y + ball.vy > canvas.height || ball.y + ball.vy < 0) { + ball.vy = -ball.vy; + } + if (ball.x + ball.vx > canvas.width || ball.x + ball.vx < 0) { + ball.vx = -ball.vx; + } + + raf = window.requestAnimationFrame(draw); +} + +canvas.addEventListener('mousemove', function(e) { + if (!running) { + clear(); + ball.x = e.clientX; + ball.y = e.clientY; + ball.draw(); + } +}); + +canvas.addEventListener('click', function(e) { + if (!running) { + raf = window.requestAnimationFrame(draw); + running = true; + } +}); + +canvas.addEventListener('mouseout', function(e) { + window.cancelAnimationFrame(raf); + running = false; +}); + +ball.draw(); +</pre> + +<p>用你的滑鼠移動這顆球且點擊鬆放它。</p> + +<p>{{EmbedLiveSample("Adding_mouse_control", "610", "310")}}</p> + +<h2 id="突破性(遊戲)">突破性(遊戲)</h2> + +<p>這個小章節只有解釋一些創造高級動畫的技巧。這裡還有更多!如何增加槳,磚塊,到這個 到 <a href="http://en.wikipedia.org/wiki/Breakout_%28video_game%29">Breakout</a> game demo去看，有我們更<a href="/en-US/docs/Games">多遊戲研發</a>的文章! </p> + +<h2 id="延伸閱讀">延伸閱讀</h2> + +<ul> + <li>{{domxref("window.requestAnimationFrame()")}}</li> + <li><a href="/en-US/docs/Games/Techniques/Efficient_animation_for_web_games">Efficient animation for web games</a></li> +</ul> + +<p>{{PreviousNext("Web/API/Canvas_API/Tutorial/Basic_animations", "Web/API/Canvas_API/Tutorial/Pixel_manipulation_with_canvas")}}</p> diff --git a/files/zh-tw/web/api/canvas_api/tutorial/applying_styles_and_colors/index.html b/files/zh-tw/web/api/canvas_api/tutorial/applying_styles_and_colors/index.html new file mode 100644 index 0000000000..86e41e3476 --- /dev/null +++ b/files/zh-tw/web/api/canvas_api/tutorial/applying_styles_and_colors/index.html @@ -0,0 +1,669 @@ +--- +title: 套用樣式與顏色 +slug: Web/API/Canvas_API/Tutorial/Applying_styles_and_colors +translation_of: Web/API/Canvas_API/Tutorial/Applying_styles_and_colors +--- +<div>{{CanvasSidebar}} {{PreviousNext("Web/API/Canvas_API/Tutorial/Drawing_shapes", "Web/API/Canvas_API/Tutorial/Drawing_text")}}</div> + +<p>在<a href="/en-US/docs//zh-TW/docs/Web/Guide/HTML/Canvas_tutorial/Drawing_shapes" title="/en-US/docs//en-US/docs/Web/Guide/HTML/Canvas_tutorial/Drawing_shapes">繪畫圖形</a>章節中，我們只用了預設的線條與填滿樣式，而在本章，我們將進一步看看所有可用的樣式選項，畫出更吸引人的圖。</p> + +<h2 id="Colors" name="Colors">顏色</h2> + +<p>U截至目前為止我們只有看到繪圖環境的方法(methods)，如果我們想要設定圖形的顏色，我們有兩個屬性能用: <code>fillStyle</code>與<code>storkeStyle.</code></p> + +<dl> + <dt><code>fillStyle = <em>color</em></code></dt> + <dd>設定填滿圖形時用的顏色.</dd> + <dt><code>strokeStyle = <em>color</em></code></dt> + <dd>設定勾勒圖形時用的顏色.</dd> +</dl> + +<p>其中<code>color</code>可以是CSS{{cssxref("<color>")}}表示字串、漸層色物件(gradient color)或是模式物件(pattern object)，現在先看一下CSS{<color>}表示字串，稍後再看另外兩個項目.</p> + +<p>預設上勾勒和填滿色是黑色(CSS顏色值為#000000).</p> + +<div class="note"> +<p><strong>Note:</strong> 一旦改變了strokeStyle的顏色值，那麼之後圖形勾勒顏色都會變成新顏色，同樣狀況一樣適用於fillStyle.</p> +</div> + +<p>合格的顏色值請參照CSS3{{cssxref("<color>")}}規範，下面範例所標示的顏色都指向同一個顏色.</p> + +<pre class="brush: js">// these all set the fillStyle to 'orange' + +ctx.fillStyle = "orange"; +ctx.fillStyle = "#FFA500"; +ctx.fillStyle = "rgb(255,165,0)"; +ctx.fillStyle = "rgba(255,165,0,1)"; +</pre> + +<div class="note"> +<p><strong>Note:</strong> 目前Gecko引擎並不支援CSS3全部的顏色值，例如hsl(100%,25%,0)和rgb(0,100%,0)就不被支援.</p> +</div> + +<h3 id="A_fillStyle_example" name="A_fillStyle_example"><code>fillStyle</code>範例</h3> + +<p>這裡我們利用兩個for迴圈來畫出一個矩形陣列，而且陣列中每一個矩形的顏色都不相同。下面程式碼透過改變i和j兩個變數來分別變換RGB中的紅色值和綠色值，然後為每一個矩形產生自己專屬的顏色值。透過改變RGB的各顏色值，我們可以產生各式各樣的調色盤，像是逐步調整顏色值，你也可以做出像Photoshop內建一樣的調色盤。</p> + +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + for (var i=0;i<6;i++){ + for (var j=0;j<6;j++){ + ctx.fillStyle = 'rgb(' + Math.floor(255-42.5*i) + ',' + + Math.floor(255-42.5*j) + ',0)'; + ctx.fillRect(j*25,i*25,25,25); + } + } +}</pre> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" width="150" height="150"></canvas></pre> + +<pre class="brush: js">draw();</pre> +</div> + +<p>結果如下:</p> + +<p>{{EmbedLiveSample("A_fillStyle_example", 160, 160, "https://mdn.mozillademos.org/files/5417/Canvas_fillstyle.png")}}</p> + +<h3 id="A_strokeStyle_example" name="A_strokeStyle_example"><code>strokeStyle</code>範例</h3> + +<p>本例和前例相當類似，不同的是我們改用arc()方法畫圓形而不是矩形、改設定strokeStyle變換圖形輪廓顏色。</p> + +<pre class="brush: js"> function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + for (var i=0;i<6;i++){ + for (var j=0;j<6;j++){ + ctx.strokeStyle = 'rgb(0,' + Math.floor(255-42.5*i) + ',' + + Math.floor(255-42.5*j) + ')'; + ctx.beginPath(); + ctx.arc(12.5+j*25,12.5+i*25,10,0,Math.PI*2,true); + ctx.stroke(); + } + } + } +</pre> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" width="150" height="150"></canvas></pre> + +<pre class="brush: js">draw();</pre> +</div> + +<p>結果如下:</p> + +<p>{{EmbedLiveSample("A_strokeStyle_example", "180", "180", "https://mdn.mozillademos.org/files/253/Canvas_strokestyle.png")}}</p> + +<h2 id="Transparency" name="Transparency">透明度</h2> + +<p>透過設定globalAlpha屬性或是以半透明顏色值設定strokeStyle與fillStyle屬性，除了畫不透明的圖形，我們還可以畫半透明的圖形。</p> + +<dl> + <dt><code>globalAlpha = <em>transparencyValue</em></code></dt> + <dd>允許值介於0.0(全透明)到1.0(不透明)。一旦設定後，之後畫布上畫的所有圖形的不透明度都會套用此設定值。預設值為1.0。</dd> +</dl> + +<p>當我們想畫一系列相同不透明度的圖，設定globalAlpha值是一個方便的作法。</p> + +<p>由CSS3顏色值能夠指定不透明度，我們也可以如下面一般，設定strokeStyle以及fillStyle來變更不透明度。</p> + +<pre class="brush: js">// Assigning transparent colors to stroke and fill style + +ctx.strokeStyle = "rgba(255,0,0,0.5)"; +ctx.fillStyle = "rgba(255,0,0,0.5)"; +</pre> + +<p>rgba()函數比rgb()函數多出一個不透明度參數，允許值介於0.0(全透明)到1.0(不透明).</p> + +<h3 id="A_globalAlpha_example" name="A_globalAlpha_example"><code>globalAlpha</code>範例</h3> + +<p>下面我們將在四個方格色塊背景上畫一系列半透明圓形。對於所有圓形，我們藉由設置globalAlpha屬性值為0.2使得圓形變成半透明，然後for迴圈裡我們逐一增加圓形繪圖半徑，最終結果看起來便像是輻射狀漸層圖案，而且圓形相互疊加在彼此之上後，又加深了重疊區域的不透明度，只要我們不斷增加圓形數量，最後圖片中央將被完全遮蓋，看不到背後的背景。</p> + +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + // draw background + ctx.fillStyle = '#FD0'; + ctx.fillRect(0,0,75,75); + ctx.fillStyle = '#6C0'; + ctx.fillRect(75,0,75,75); + ctx.fillStyle = '#09F'; + ctx.fillRect(0,75,75,75); + ctx.fillStyle = '#F30'; + ctx.fillRect(75,75,150,150); + ctx.fillStyle = '#FFF'; + + // set transparency value + ctx.globalAlpha = 0.2; + + // Draw semi transparent circles + for (i=0;i<7;i++){ + ctx.beginPath(); + ctx.arc(75,75,10+10*i,0,Math.PI*2,true); + ctx.fill(); + } +}</pre> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" width="150" height="150"></canvas></pre> + +<pre class="brush: js">draw();</pre> +</div> + +<p>{{EmbedLiveSample("A_globalAlpha_example", "180", "180", "https://mdn.mozillademos.org/files/232/Canvas_globalalpha.png")}}</p> + +<h3 id="An_example_using_rgba()" name="An_example_using_rgba()"><code>rgba()</code>使用範例</h3> + +<p>這個範例類似於上面的範例，但不同的是我們改畫半透明的矩形。rgba()在使用上會多一點彈性，因為我們可以分別設置勾勒和填滿圖形的不透明度。</p> + +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + + // Draw background + ctx.fillStyle = 'rgb(255,221,0)'; + ctx.fillRect(0,0,150,37.5); + ctx.fillStyle = 'rgb(102,204,0)'; + ctx.fillRect(0,37.5,150,37.5); + ctx.fillStyle = 'rgb(0,153,255)'; + ctx.fillRect(0,75,150,37.5); + ctx.fillStyle = 'rgb(255,51,0)'; + ctx.fillRect(0,112.5,150,37.5); + + // Draw semi transparent rectangles + for (var i=0;i<10;i++){ + ctx.fillStyle = 'rgba(255,255,255,'+(i+1)/10+')'; + for (var j=0;j<4;j++){ + ctx.fillRect(5+i*14,5+j*37.5,14,27.5) + } + } +}</pre> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" width="150" height="150"></canvas></pre> + +<pre class="brush: js">draw();</pre> +</div> + +<p>{{EmbedLiveSample("An_example_using_rgba()", "180", "180", "https://mdn.mozillademos.org/files/246/Canvas_rgba.png")}}</p> + +<h2 id="Line_styles" name="Line_styles">線條樣式</h2> + +<p>有數種屬性可以讓我們設定線條樣式.</p> + +<dl> + <dt><code>lineWidth = <em>value</em></code></dt> + <dd>設定線條寬度。</dd> + <dt><code>lineCap = <em>type</em></code></dt> + <dd>設定線條結尾的樣式。</dd> + <dt><code>lineJoin = <em>type</em></code></dt> + <dd>設定線條和線條間接合處的樣式。</dd> + <dt><code>miterLimit = <em>value</em></code></dt> + <dd>限制當兩條線相交時交接處最大長度；所謂交接處長度(miter length)是指線條交接處內角頂點到外角頂點的長度。</dd> +</dl> + +<p>底下我們將一一示範這些屬性的用途。</p> + +<h3 id="A_lineWidth_example" name="A_lineWidth_example"><code>lineWidth</code>範例</h3> + +<p>此屬性決定線條寬度，必須為正數，預設值為1.0單位。</p> + +<p>線條寬度的起算點是從繪圖路徑中央開始往兩旁各延伸一半設定寬度，由於畫布座標不直接對應到像素(pixel)，所以要比較小心設定好取得清晰的直線。</p> + +<p>由下方例子可以明顯看到，畫布上有10條直線，由左至右，從最小的1.0單位寬開始逐漸加寬，請注意奇數寬度直線會因為繪圖路徑位置關係而比較模糊。</p> + +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + for (var i = 0; i < 10; i++){ + ctx.lineWidth = 1+i; + ctx.beginPath(); + ctx.moveTo(5+i*14,5); + ctx.lineTo(5+i*14,140); + ctx.stroke(); + } +} +</pre> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" width="150" height="150"></canvas></pre> + +<pre class="brush: js">draw();</pre> +</div> + +<p>{{EmbedLiveSample("A_lineWidth_example", "180", "180", "https://mdn.mozillademos.org/files/239/Canvas_linewidth.png")}}</p> + +<p>為了畫出清晰的直線，我們需要了解繪圖路徑是如何產生；如下方圖示，網格代表畫布座標軸，網格所框出的方格則代表螢幕上的像素，第一張圖片填滿了座標(2,1)到(5,5)的紅色區域，而這個紅色區域的邊際正好符合像素間的邊際，所以會產生出清晰的影像。</p> + +<p><img alt="" class="internal" src="https://mdn.mozillademos.org/files/201/Canvas-grid.png"></p> + +<p>第二張圖片中，有一條寬1.0單位的直線從座標(3,1)到(3,5)被畫在畫布上，不過由於線條寬度的起算點是從繪圖路徑中央開始往兩旁各延伸一半設定寬度，所以當勾勒線條時，繪圖路徑兩旁的像素格只有一半會被填滿暗藍色，至於另外一半則會經由計算填入近似色(淡藍色)，結果就是整格像素並非全部填入相同的暗藍色，進而產生出邊緣較為模糊的線條，上面程式碼範例中的奇數寬度直線就是因此而產生不清晰的線條。</p> + +<p>為了避免劃出邊緣模糊直線，我們必須精準設定繪圖路徑位置，就本範例而言，如果我們的直線繪圖路徑是從座標(3.5, 1)到(3.5, 5)的話(如第三張圖)，那麼1.0單位寬的直線將剛好填滿像素格，所以我們將可以畫出清晰的直線。</p> + +<div class="note"> +<p><strong>Note:</strong> 請注意本範例的Y軸座標都是整數點，若非如此，一樣會導致線條端點的像素格無法剛好被填滿的現象，而且同時最後產生的結果也會被lineCap給影響；倘若lineCap值為預設butt時，我們會需要為奇數寬度直線計算一下非整數的座標點，倘若lineCap樣式為square，那麼線段端點的像素格將自動被完整填滿。</p> + +<p>還有一點需要注意，只要繪圖路徑被closePath()函數閉合起來，這樣便沒有了線條端點，所有的線條端點都會依據lineJoin樣式全部前後互相連接起來，這會自動延伸端點邊緣到線段接合處，如果此時接合端點是水平或垂直的話，位於中央的像素格將會被完整填滿。後面的說明會介紹lineCap和lineJoin樣式。</p> +</div> + +<p>至於本例中偶數寬度的直線，為了避免模糊，繪圖路徑最好是落在整數座標點上。</p> + +<p>雖然處裡2D繪圖縮放有些麻煩，但只要仔細計算像素格和繪圖路徑位置，縱使進行圖像縮放或變形，圖像輸出還是可以保持正確。一條寬1.0單位的直線，只要位置計算正確，放大兩倍後會變成一條2個像素寬的清晰直線，而且還是會保持正確位置。</p> + +<h3 id="A_lineCap_example" name="A_lineCap_example"><code>lineCap</code>範例</h3> + +<p>這個屬性決定線條端點的樣式，總共有三種樣式可選:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/236/Canvas_linecap.png" style="float: right; height: 190px; width: 190px;"></p> + +<dl> + <dt><code>butt</code></dt> + <dd>線條端點樣式為方形</dd> + <dt><code>round</code></dt> + <dd>線條端點樣式為圓形</dd> + <dt><code>square</code></dt> + <dd>增加寬同線條寬度、高線條寬度一半的的方塊於線條端點</dd> +</dl> + +<p>下面程式碼會畫出三條線，每條線的lineCap值皆不同。然後為了看清差異點，我們加上了兩條淡藍色的輔助線，線條的繪圖起始點和終點都剛好落在輔助線上。</p> + +<p>最左邊的線條其lineCap為butt，不難看出它完全介於輔助線之間；第二條線其lineCap為round，端點樣式為半徑等於線條寬度一半的半圓；最右邊的線條其lineCap為square，端點樣式為寬同線條寬度、高線條寬度一半的的方塊。</p> + +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + var lineCap = ['butt','round','square']; + + // Draw guides + ctx.strokeStyle = '#09f'; + ctx.beginPath(); + ctx.moveTo(10,10); + ctx.lineTo(140,10); + ctx.moveTo(10,140); + ctx.lineTo(140,140); + ctx.stroke(); + + // Draw lines + ctx.strokeStyle = 'black'; + for (var i=0;i<lineCap.length;i++){ + ctx.lineWidth = 15; + ctx.lineCap = lineCap[i]; + ctx.beginPath(); + ctx.moveTo(25+i*50,10); + ctx.lineTo(25+i*50,140); + ctx.stroke(); + } +} +</pre> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" width="150" height="150"></canvas></pre> + +<pre class="brush: js">draw();</pre> +</div> + +<p>{{EmbedLiveSample("A_lineCap_example", "180", "180", "https://mdn.mozillademos.org/files/236/Canvas_linecap.png")}}</p> + +<h3 id="A_lineJoin_example" name="A_lineJoin_example"><code>lineJoin</code>範例</h3> + +<p>lineJoin屬性決定兩個連接區端(如線條、弧形或曲線)如何連接(對於長度為零，亦即終點和控制點為同一點的圖形無效)。</p> + +<p>lineJoin屬性共有三個屬性值如下，其中miter為預設值，請注意一點若是兩個連接區段的繪圖方向一致，那代表不會有連接處，所以測定是無效的。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/237/Canvas_linejoin.png" style="float: right; height: 190px; width: 190px;"></p> + +<dl> + <dt><code>round</code></dt> + <dd>代表圓弧型連接樣式。</dd> + <dt><code>bevel</code></dt> + <dd>代表斜面型連接樣式。在連接區段的共同終點處填滿一個三角形區域，將原本的外接角處形成一個切面。</dd> + <dt><code>miter</code></dt> + <dd>代表斜交型連接樣式。向外延伸連結區段外緣直到相交於一點，然後形成菱形區域，而miterLimit屬性會影響miter屬性。</dd> +</dl> + +<p>下方程式碼和圖形輸出展示了lineJoin在不同屬性值下呈現的不同結果</p> + +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + var lineJoin = ['round','bevel','miter']; + ctx.lineWidth = 10; + for (var i=0;i<lineJoin.length;i++){ + ctx.lineJoin = lineJoin[i]; + ctx.beginPath(); + ctx.moveTo(-5,5+i*40); + ctx.lineTo(35,45+i*40); + ctx.lineTo(75,5+i*40); + ctx.lineTo(115,45+i*40); + ctx.lineTo(155,5+i*40); + ctx.stroke(); + } +} +</pre> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" width="150" height="150"></canvas></pre> + +<pre class="brush: js">draw();</pre> +</div> + +<p>{{EmbedLiveSample("A_lineJoin_example", "180", "180", "https://mdn.mozillademos.org/files/237/Canvas_linejoin.png")}}</p> + +<h3 id="A_demo_of_the_miterLimit_property" name="A_demo_of_the_miterLimit_property"><code>miterLimit</code>屬性</h3> + +<p>前面範例顯示出，當lineJoin值為miter時，兩條線的外緣會延伸相交，所以，當這兩條相交線的相交角度越小的話，他們的延伸交會點就會越遠離內緣連接點，而且隨著角度變小，距離呈指數型增長。</p> + +<p>miterLimit會限制延伸交會點最遠可以離內緣連接點到多遠，當延伸交會點的落點超出這個範圍，那麼便以斜面(bevel)作為交接樣式。請注意，最大miter長度為線寬乘於miterLimit值，所以miterLimit可以獨立於目前顯示縮放尺寸或其他變形設定。</p> + +<p>miterLimit預設值為10.0。</p> + +<p>更精確來說，miter限制是指延伸長度(在HTML畫布上，這個長度是外緣相交角到連接區段的共同繪圖路經終點)相對於一半線寬的最大允許比率；也等同於，外緣距內緣相交點之距離相對於線寬的的最大允許比率；相當於，連接區最小內緣角的一半角度的餘割(cosecant)值, 小於此值則便以斜面(bevel)作為交接樣式:</p> + +<ul> + <li><code>miterLimit</code> = <strong>max</strong> <code>miterLength</code> / <code>lineWidth</code> = 1 / <strong>sin</strong> ( <strong>min</strong> <em>θ</em> / 2 )</li> + <li>10.0的預設miterLimit值會移除任何角度小於11度的相接線段的miter交接。</li> + <li>miter限制值如果等於根號2(約1.4142136)會移除銳角的miter交接，只有直角或鈍角的不會被移除。</li> + <li>miter限制值如果等於1.0會移除所有的miter交接。</li> + <li>小於1.0不是合法的限制值。</li> +</ul> + +<p>下面是一個範例，其中藍線標示出各個線條繪圖路徑的起始點與終點。</p> + +<p>倘若設定範例程式碼中的miterLimit低於4.2，所有的miter交接都會被移除，取而代之的是出現在藍線附近的bevel交接；倘若設定miterLimit大於10，那麼大部分的miter交接都會出現，而且你會發現，由左到右，miter長度逐漸縮短，這是由於線條相交角度逐漸加大之故；倘若設定中間值，那麼左邊會出現bevel交接，右邊會出現miter交接。</p> + +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + + // Clear canvas + ctx.clearRect(0,0,150,150); + + // Draw guides + ctx.strokeStyle = '#09f'; + ctx.lineWidth = 2; + ctx.strokeRect(-5,50,160,50); + + // Set line styles + ctx.strokeStyle = '#000'; + ctx.lineWidth = 10; + + // check input + if (document.getElementById('miterLimit').value.match(/\d+(\.\d+)?/)) { + ctx.miterLimit = parseFloat(document.getElementById('miterLimit').value); + } else { + alert('Value must be a positive number'); + } + + // Draw lines + ctx.beginPath(); + ctx.moveTo(0,100); + for (i=0;i<24;i++){ + var dy = i%2==0 ? 25 : -25 ; + ctx.lineTo(Math.pow(i,1.5)*2,75+dy); + } + ctx.stroke(); + return false; +} +</pre> + +<div class="hidden"> +<pre class="brush: html"><table> + <tr> + <td><canvas id="canvas" width="150" height="150"></canvas></td> + <td>Change the <code>miterLimit</code> by entering a new value below and clicking the redraw button.<br><br> + <form onsubmit="return draw();"> + <label>Miter limit</label> + <input type="text" size="3" id="miterLimit"/> + <input type="submit" value="Redraw"/> + </form> + </td> + </tr> +</table></pre> + +<pre class="brush: js">document.getElementById('miterLimit').value = document.getElementById('canvas').getContext('2d').miterLimit; +draw();</pre> +</div> + +<p>{{EmbedLiveSample("A_demo_of_the_miterLimit_property", "400", "180", "https://mdn.mozillademos.org/files/240/Canvas_miterlimit.png")}}</p> + +<h2 id="Gradients" name="Gradients">漸層</h2> + +<p>如同其他繪圖軟體可以畫出線性和放射狀的漸層圖案，透過設定fillStyle和strokeStyle屬性為canvasGradient漸層物件，我們也可以在canvas上做到一樣的效果。要創造漸層物件，可以使用下面的方法:</p> + +<dl> + <dt><code>createLinearGradient(<em>x1</em>, <em>y1</em>, <em>x2</em>, <em>y2</em>)</code></dt> + <dd>產生一個線性漸層物件，其漸層起始點為(x1, y1)、終點為(x2, y2)。</dd> + <dt><code>createRadialGradient(<em>x1</em>, <em>y1</em>, <em>r1</em>, <em>x2</em>, <em>y2</em>, <em>r2</em>)</code></dt> + <dd>產生一個放射狀漸層物件，第一個圓之圓心落在(x1, y1)、半徑為r1，第一個圓之圓心落在(x2, y2)、半徑為r2。</dd> +</dl> + +<p>例如:</p> + +<pre class="brush: js">var lineargradient = ctx.createLinearGradient(0, 0, 150, 150); +var radialgradient = ctx.createRadialGradient(75, 75, 0, 75, 75, 100); +</pre> + +<p>一旦產生了canvasGradient漸層物件，我們用addColorStop()方法可以添加顏色上去。</p> + +<dl> + <dt><code><em>gradient</em>.addColorStop(<em>position</em>, <em>color</em>)</code></dt> + <dd>於gradient漸層物件建立一個顏色點，其中color是CSS{{cssxref("<color>")}}的字串表示，而position介於0.0到1.0之間，定義了該顏色在漸層中的相對位置。呼叫這個方法會指定當進行到設定的位置時，漸層需要完全轉變成設定的顏色。</dd> +</dl> + +<p>我們可以按照需要設定無數個顏色點，下面是一個簡單的由白到黑的簡單漸層範例程式碼。</p> + +<pre class="brush: js">var lineargradient = ctx.createLinearGradient(0,0,150,150); +lineargradient.addColorStop(0, 'white'); +lineargradient.addColorStop(1, 'black'); +</pre> + +<h3 id="A_createLinearGradient_example" name="A_createLinearGradient_example"><code>createLinearGradient</code>範例</h3> + +<p>本範例中，我們將建立兩種漸層，如範例所示，strokeStyle和fillSyle屬性都可以接受canvasGradient物件作為屬性值。</p> + +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + + // Create gradients + var lingrad = ctx.createLinearGradient(0,0,0,150); + lingrad.addColorStop(0, '#00ABEB'); + lingrad.addColorStop(0.5, '#fff'); + lingrad.addColorStop(0.5, '#26C000'); + lingrad.addColorStop(1, '#fff'); + + var lingrad2 = ctx.createLinearGradient(0,50,0,95); + lingrad2.addColorStop(0.5, '#000'); + lingrad2.addColorStop(1, 'rgba(0,0,0,0)'); + + // assign gradients to fill and stroke styles + ctx.fillStyle = lingrad; + ctx.strokeStyle = lingrad2; + + // draw shapes + ctx.fillRect(10,10,130,130); + ctx.strokeRect(50,50,50,50); + +} +</pre> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" width="150" height="150"></canvas></pre> + +<pre class="brush: js">draw();</pre> +</div> + +<p>第一個漸層為背景漸層，範例中我們在一個位置上指定了兩種顏色(白色到綠色)，這樣做會產生非常突然的顏色轉換，一般來說，不管如何設定顏色點順序都沒關係，然而就這個例子而言，這種作法太過強烈了，但是如果這是你想要的顏色漸層順序，那其實也是可以。</p> + +<p>第二個漸層起始位置(position 0.0)的顏色並沒有被指定，所以下一個漸層顏色會自動被設為起始位置顏色，因此即使我們沒有指定漸層起始位置顏色也沒有關係，就像本範例自動會設定起始位置的顏色等於位置0.5的黑色。</p> + +<p>{{EmbedLiveSample("A_createLinearGradient_example", "180", "180", "https://mdn.mozillademos.org/files/235/Canvas_lineargradient.png")}}</p> + +<h3 id="A_createRadialGradient_example" name="A_createRadialGradient_example"><code>createRadialGradient</code>範例</h3> + +<p>這邊我們定義了四種放射狀漸層，相較於一般在Photoshop看到的”經典”放射狀漸層圖案(漸層從一個圖案中心點向外呈圓心狀延伸)，因為我們可以控制漸層起始和終止點，我們可以做到更好的效果。</p> + +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + + // Create gradients + var radgrad = ctx.createRadialGradient(45,45,10,52,50,30); + radgrad.addColorStop(0, '#A7D30C'); + radgrad.addColorStop(0.9, '#019F62'); + radgrad.addColorStop(1, 'rgba(1,159,98,0)'); + + var radgrad2 = ctx.createRadialGradient(105,105,20,112,120,50); + radgrad2.addColorStop(0, '#FF5F98'); + radgrad2.addColorStop(0.75, '#FF0188'); + radgrad2.addColorStop(1, 'rgba(255,1,136,0)'); + + var radgrad3 = ctx.createRadialGradient(95,15,15,102,20,40); + radgrad3.addColorStop(0, '#00C9FF'); + radgrad3.addColorStop(0.8, '#00B5E2'); + radgrad3.addColorStop(1, 'rgba(0,201,255,0)'); + + var radgrad4 = ctx.createRadialGradient(0,150,50,0,140,90); + radgrad4.addColorStop(0, '#F4F201'); + radgrad4.addColorStop(0.8, '#E4C700'); + radgrad4.addColorStop(1, 'rgba(228,199,0,0)'); + + // draw shapes + ctx.fillStyle = radgrad4; + ctx.fillRect(0,0,150,150); + ctx.fillStyle = radgrad3; + ctx.fillRect(0,0,150,150); + ctx.fillStyle = radgrad2; + ctx.fillRect(0,0,150,150); + ctx.fillStyle = radgrad; + ctx.fillRect(0,0,150,150); +} +</pre> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" width="150" height="150"></canvas></pre> + +<pre class="brush: js">draw();</pre> +</div> + +<p>程式碼範例中，為了營造出3D效果，我們讓起始點和終止點位於不同位置，請注意，最好不要讓內外圈相重疊，以避免難以預測的奇怪效果。</p> + +<p>每一個漸層圖案最後一個漸層色都是全透明的，如果希望倒數第二個漸層色能夠平順地轉換到這個最後一個漸層色，那麼兩者應該設定一樣的顏色值，像是程式碼範例中的漸層色 #019F62 其實就等於 rgba(1,159,98,1)。</p> + +<p>{{EmbedLiveSample("A_createRadialGradient_example", "180", "180", "https://mdn.mozillademos.org/files/244/Canvas_radialgradient.png")}}</p> + +<h2 id="Patterns" name="Patterns">樣式(Patterns)</h2> + +<p>先前的範例中，我們都是藉由迴圈來重複產生影像樣式，不過其實有一條更簡單的方法，那就是呼叫createPattern方法。</p> + +<dl> + <dt><code>createPattern(<em>image</em>, <em>type</em>)</code></dt> + <dd>呼叫createPattern()會產一個畫布樣式物件，然後回傳出來。<br> + 其中image是<a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#image-sources-for-2d-rendering-contexts" title="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#image-sources-for-2d-rendering-contexts">CanvasImageSource</a>類別物件(像是{{domxref("HTMLImageElement")}},、<canvas>元素、{{HTMLElement("video")}} 元素等)</dd> +</dl> + +<p>Type是一串字串，定義了如何產生樣式，允許的值有:</p> + +<dl> + <dt><code>repeat</code></dt> + <dd>沿垂直與水平方向重複排列影像</dd> + <dt><code>repeat-x</code></dt> + <dd>只沿水平方向重複排列影像</dd> + <dt><code>repeat-y</code></dt> + <dd>只沿垂直方向重複排列影像</dd> + <dt><code>no-repeat</code></dt> + <dd>不重複排列影像，只使用一次</dd> +</dl> + +<div class="note"> +<p><strong>Note:</strong> Firefox現在只支援repeat，所以其他值都是無效的</p> +</div> + +<div class="note"><strong>Note:</strong> 傳入尺寸為0x0像素的畫布會引起錯誤</div> + +<p>利用createPattern()的方法和前面利用漸層的方法十分類似，我們呼叫createPattern()產生{{domxref("CanvasPattern")}}物件，然後將{CanvasPattern}物件設成fillStyle或strokeStyle的屬性值，例如:</p> + +<pre class="brush: js">var img = new Image(); +img.src = 'someimage.png'; +var ptrn = ctx.createPattern(img,'repeat'); +</pre> + +<div class="note"> +<p><strong>Note:</strong> 不像drawImage()方法，呼叫createPattern()方法前影像必須要先載入完成，否則可能圖像的程生會有問題。</p> +</div> + +<h3 id="A_createPattern_example" name="A_createPattern_example"><code>createPattern</code>範例</h3> + +<p>這個範例中我們把fillStyle屬性值存為樣式物件，比較值得注意的是影像onload事件處理器，這是為了確保影像載入完成後再進行。</p> + +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + + // create new image object to use as pattern + var img = new Image(); + img.src = '/files/222/Canvas_createpattern.png'; + img.onload = function(){ + + // create pattern + var ptrn = ctx.createPattern(img,'repeat'); + ctx.fillStyle = ptrn; + ctx.fillRect(0,0,150,150); + + } +} +</pre> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" width="150" height="150"></canvas></pre> + +<pre class="brush: js">draw();</pre> + +<p>結果如下<span style="display: none;"> </span>:</p> +</div> + +<p>{{EmbedLiveSample("A_createPattern_example", "180", "180", "https://mdn.mozillademos.org/files/222/Canvas_createpattern.png")}}</p> + +<h2 id="陰影">陰影</h2> + +<p>要產生陰影只需要四個屬性:</p> + +<dl> + <dt><code>shadowOffsetX = <em>float</em></code></dt> + <dd>代表陰影從物件延伸出來的水平距離，預設為0，不受變形矩陣影響。</dd> + <dt><code>shadowOffsetY = <em>float</em></code></dt> + <dd>代表陰影從物件延伸出來的垂直距離，預設為0，不受變形矩陣影響。</dd> + <dt><code>shadowBlur = <em>float</em></code></dt> + <dd>代表陰影模糊大小範圍，預設為0，不受變形矩陣影響，不等同於像素值。</dd> + <dt><code>shadowColor = {{cssxref("<color>")}}</code></dt> + <dd>CSS顏色值，代表陰影顏色，預設為全透明。</dd> +</dl> + +<p><code>shadowOffsetX和shadowOffsetY會決定陰影延伸大小，若是為正值，則陰影會往右(沿X軸)和往下(沿Y軸)延伸，若是為負值，則會往正值相反方向延伸。</code></p> + +<div class="geckoVersionNote"> +<p>{{gecko_callout_heading("7.0")}}</p> + +<p>Note: 基於HTML5提議規格變更，從{{Gecko("7.0")}}開始，陰影只會在source-over的<a href="/en-US/docs/Web/Guide/HTML/Canvas_tutorial/Compositing" title="/en-US/docs/Web/Guide/HTML/Canvas_tutorial/Compositing">構圖排列</a>下產生</p> +</div> + +<h3 id="文字陰影範例">文字陰影範例</h3> + +<p>本程式碼範例會產生一串帶有陰影的文字。</p> + +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + + ctx.shadowOffsetX = 2; + ctx.shadowOffsetY = 2; + ctx.shadowBlur = 2; + ctx.shadowColor = "rgba(0, 0, 0, 0.5)"; + + ctx.font = "20px Times New Roman"; + ctx.fillStyle = "Black"; + ctx.fillText("Sample String", 5, 30); +} +</pre> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" width="150" height="80"></canvas></pre> + +<pre class="brush: js">draw();</pre> +</div> + +<p>{{EmbedLiveSample("A_shadowed_text_example", "180", "100", "https://mdn.mozillademos.org/files/2505/shadowed-string.png")}}</p> + +<p>{{PreviousNext("Web/Guide/HTML/Canvas_tutorial/Using_images", "Web/Guide/HTML/Canvas_tutorial/Transformations")}}</p> + +<div id="cke_pastebin" style="position: absolute; top: 12776.2px; width: 1px; height: 1px; overflow: hidden; left: -1000px;"> </div> diff --git a/files/zh-tw/web/api/canvas_api/tutorial/basic_animations/index.html b/files/zh-tw/web/api/canvas_api/tutorial/basic_animations/index.html new file mode 100644 index 0000000000..336fadbce0 --- /dev/null +++ b/files/zh-tw/web/api/canvas_api/tutorial/basic_animations/index.html @@ -0,0 +1,347 @@ +--- +title: 基礎動畫 +slug: Web/API/Canvas_API/Tutorial/Basic_animations +translation_of: Web/API/Canvas_API/Tutorial/Basic_animations +--- +<div>{{CanvasSidebar}} {{PreviousNext("Web/API/Canvas_API/Tutorial/Compositing", "Web/API/Canvas_API/Tutorial/Advanced_animations")}}</div> + +<p>控制{{HTMLElement("canvas")}}元素來產生互動式動畫不是一件難事，當然，如果產生的動畫越複雜越需要多費一些力氣，未來如果有機會我們將說明這一塊。</p> + +<p>由於圖形一但產生後便靜止不動，所以我們必須重新繪圖好移動圖案，產生動畫效果，所以如果繪圖越複雜，繪圖運算也需要消耗越多運算資源和時間，換句話說，電腦效能的好壞將大大影響動畫順暢度，或許這也是畫布動畫最大的限制。</p> + +<h2 id="Basic_animation_steps" name="Basic_animation_steps">動畫基本步驟</h2> + +<p>產生一個畫面基本上需要以下步驟 :</p> + +<ol> + <li><strong>清除畫布</strong><br> + 除了不變的背景畫面，所有先前畫的圖案都要先清除，這個步驟可以透過clearRect()方法達成。</li> + <li><strong>儲存畫布狀態</strong><br> + 若是想要每一次重新繪圖時畫布起始狀態都是原始狀態，那麼就需要先行儲存畫布原始狀態。</li> + <li><strong>畫出畫面</strong><br> + 畫出需要畫面。</li> + <li><strong>復原畫布狀態</strong><br> + 復原畫布狀態以備下次繪圖使用。</li> +</ol> + +<h2 id="Controlling_an_animation" name="Controlling_an_animation">控制動畫</h2> + +<p>一般來說當程式碼執行完畢後我們才會看到繪圖結果，所以說我們無法靠執行for迴圈來產生動畫，我們得靠每隔一段時間繪圖來產生動畫，下面將介紹兩種作法。</p> + +<h3 id="排程更新">排程更新</h3> + +<p>第一種作法是利用{{domxref("window.setInterval()")}}與{{domxref("window.setTimeout()")}}方法。</p> + +<div class="note"> +<p><strong>Note:</strong> 針對新版瀏覽器建議採用{{domxref("window.requestAnimationFrame()")}}方法。</p> +</div> + +<dl> + <dt><code>setInterval(<em>function</em>, <em>delay</em>)</code></dt> + <dd>每隔delay毫秒，執行輸入function(函數)</dd> + <dt><code>setTimeout(<em>function</em>, <em>delay</em>)</code></dt> + <dd>過delay毫秒後，執行輸入function(函數)</dd> + <dt>requestAnimationFrame(callback)</dt> + <dd>告訴瀏覽器你希望執行動畫的時候,要求瀏覽器在重繪下一張畫面之前,呼叫callback函數來更新動畫</dd> +</dl> + +<p>如果希望不要有任何的使用者互動影響，請使用setInterval()，因為它會確實地每隔一段時間就執行程式碼。如果你想製作遊戲 , 我們能夠使用keyboard 或是 mouse event來控制動畫,並使用setTimeout()函數一起。藉由設定EventListeners,我們能夠捕捉任何使用者的動作,並執行我們的動畫函數。</p> + +<div class="note"> +<p>在下面的範例,我們將使用<strong>window.requestAnimationFrame()</strong>方法來控制動畫,<strong>window.requestAnimationFrame()</strong>方法為動畫提供更順暢更有效率的方式來執行,當系統準備好繪製畫面時,藉由呼叫動畫andmation frame()的callback函數 。callback通常每秒鐘執行60次,當執行background tab時,執行次數會更低,想知道更多關於動畫迴圈(animation loop)的資訊,尤其是遊戲的應用,請查看我們在 <a href="https://developer.mozilla.org/en-US/docs/Games">Game development zone</a> 的主題 <a href="https://developer.mozilla.org/en-US/docs/Games/Anatomy">Anatomy of a video game</a> 。</p> +</div> + +<h3 id="從使用者輸入操作控制動畫">從使用者輸入操作控制動畫</h3> + +<p>我們也可以從使用者輸入操作控制動畫，就像是電玩遊戲一般；像是在鍵盤上設置事件處理器{{domxref("EventListener")}}捕捉使用者輸入並執行對應動畫。</p> + +<p>你可以利用我們的<a href="https://developer.mozilla.org/en-US/docs/DOM/window.setInterval#A_little_framework" title="https://developer.mozilla.org/en-US/docs/DOM/window.setInterval#A_little_framework">次要版</a>或<a href="https://developer.mozilla.org/en-US/docs/JavaScript/Timers/Daemons" title="https://developer.mozilla.org/en-US/docs/JavaScript/Timers/Daemons">主要版動畫框架</a>。</p> + +<pre>var myAnimation = new MiniDaemon(null, animateShape, 500, Infinity);</pre> + +<p>或</p> + +<pre>var myAnimation = new Daemon(null, animateShape, 500, Infinity);</pre> + +<p>在後面的範例我們主要將使用window.setInterval()方法控制動畫，然後於本頁底部是一些使用widnow.setTimeout()的範例連結。</p> + +<h4 id="太陽系動畫">太陽系動畫</h4> + +<p>本例會產生一個小型太陽系運行動畫。</p> + +<pre class="brush: js">var sun = new Image(); +var moon = new Image(); +var earth = new Image(); +function init(){ + sun.src = 'https://mdn.mozillademos.org/files/1456/Canvas_sun.png'; + moon.src = 'https://mdn.mozillademos.org/files/1443/Canvas_moon.png'; + earth.src = 'https://mdn.mozillademos.org/files/1429/Canvas_earth.png'; + setInterval(draw,100); +} + +function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + + ctx.globalCompositeOperation = 'destination-over'; + ctx.clearRect(0,0,300,300); // clear canvas + + ctx.fillStyle = 'rgba(0,0,0,0.4)'; + ctx.strokeStyle = 'rgba(0,153,255,0.4)'; + ctx.save(); + ctx.translate(150,150); + + // Earth + var time = new Date(); + ctx.rotate( ((2*Math.PI)/60)*time.getSeconds() + ((2*Math.PI)/60000)*time.getMilliseconds() ); + ctx.translate(105,0); + ctx.fillRect(0,-12,50,24); // Shadow + ctx.drawImage(earth,-12,-12); + + // Moon + ctx.save(); + ctx.rotate( ((2*Math.PI)/6)*time.getSeconds() + ((2*Math.PI)/6000)*time.getMilliseconds() ); + ctx.translate(0,28.5); + ctx.drawImage(moon,-3.5,-3.5); + ctx.restore(); + + ctx.restore(); + + ctx.beginPath(); + ctx.arc(150,150,105,0,Math.PI*2,false); // Earth orbit + ctx.stroke(); + + ctx.drawImage(sun,0,0,300,300); +} +</pre> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" width="300" height="300"></canvas></pre> + +<pre class="brush: js">init();</pre> +</div> + +<p>{{EmbedLiveSample("An_animated_solar_system", "310", "310", "https://mdn.mozillademos.org/files/202/Canvas_animation1.png")}}</p> + +<h4 id="時鐘動畫">時鐘動畫</h4> + +<p>本例會產生一個時鐘指向現在時間。</p> + +<pre class="brush: js">function init(){ + clock(); + setInterval(clock,1000); +} + +function clock(){ + var now = new Date(); + var ctx = document.getElementById('canvas').getContext('2d'); + ctx.save(); + ctx.clearRect(0,0,150,150); + ctx.translate(75,75); + ctx.scale(0.4,0.4); + ctx.rotate(-Math.PI/2); + ctx.strokeStyle = "black"; + ctx.fillStyle = "white"; + ctx.lineWidth = 8; + ctx.lineCap = "round"; + + // Hour marks + ctx.save(); + for (var i=0;i<12;i++){ + ctx.beginPath(); + ctx.rotate(Math.PI/6); + ctx.moveTo(100,0); + ctx.lineTo(120,0); + ctx.stroke(); + } + ctx.restore(); + + // Minute marks + ctx.save(); + ctx.lineWidth = 5; + for (i=0;i<60;i++){ + if (i%5!=0) { + ctx.beginPath(); + ctx.moveTo(117,0); + ctx.lineTo(120,0); + ctx.stroke(); + } + ctx.rotate(Math.PI/30); + } + ctx.restore(); + + var sec = now.getSeconds(); + var min = now.getMinutes(); + var hr = now.getHours(); + hr = hr>=12 ? hr-12 : hr; + + ctx.fillStyle = "black"; + + // write Hours + ctx.save(); + ctx.rotate( hr*(Math.PI/6) + (Math.PI/360)*min + (Math.PI/21600)*sec ) + ctx.lineWidth = 14; + ctx.beginPath(); + ctx.moveTo(-20,0); + ctx.lineTo(80,0); + ctx.stroke(); + ctx.restore(); + + // write Minutes + ctx.save(); + ctx.rotate( (Math.PI/30)*min + (Math.PI/1800)*sec ) + ctx.lineWidth = 10; + ctx.beginPath(); + ctx.moveTo(-28,0); + ctx.lineTo(112,0); + ctx.stroke(); + ctx.restore(); + + // Write seconds + ctx.save(); + ctx.rotate(sec * Math.PI/30); + ctx.strokeStyle = "#D40000"; + ctx.fillStyle = "#D40000"; + ctx.lineWidth = 6; + ctx.beginPath(); + ctx.moveTo(-30,0); + ctx.lineTo(83,0); + ctx.stroke(); + ctx.beginPath(); + ctx.arc(0,0,10,0,Math.PI*2,true); + ctx.fill(); + ctx.beginPath(); + ctx.arc(95,0,10,0,Math.PI*2,true); + ctx.stroke(); + ctx.fillStyle = "rgba(0,0,0,0)"; + ctx.arc(0,0,3,0,Math.PI*2,true); + ctx.fill(); + ctx.restore(); + + ctx.beginPath(); + ctx.lineWidth = 14; + ctx.strokeStyle = '#325FA2'; + ctx.arc(0,0,142,0,Math.PI*2,true); + ctx.stroke(); + + ctx.restore(); +}</pre> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" width="150" height="150"></canvas></pre> + +<pre class="brush: js">init();</pre> +</div> + +<p>{{EmbedLiveSample("An_animated_clock", "180", "180", "https://mdn.mozillademos.org/files/203/Canvas_animation2.png")}}</p> + +<h4 id="循環景色">循環景色</h4> + +<p>本例會產一個由左到右循環捲動<a href="http://commons.wikimedia.org/wiki/File:Capitan_Meadows,_Yosemite_National_Park.jpg" title="http://commons.wikimedia.org/wiki/File:Capitan_Meadows,_Yosemite_National_Park.jpg">美國優勝美地國家公園</a>景色，你也可以自行替換其他比畫布還大的圖片。</p> + +<pre class="brush: js">var img = new Image(); + +// User Variables - customize these to change the image being scrolled, its +// direction, and the speed. + +img.src = '/files/4553/Capitan_Meadows,_Yosemite_National_Park.jpg'; +var CanvasXSize = 800; +var CanvasYSize = 200; +var speed = 30; //lower is faster +var scale = 1.05; +var y = -4.5; //vertical offset + +// Main program + +var dx = 0.75; +var imgW; +var imgH; +var x = 0; +var clearX; +var clearY; +var ctx; + +img.onload = function() { + imgW = img.width*scale; + imgH = img.height*scale; + if (imgW > CanvasXSize) { x = CanvasXSize-imgW; } // image larger than canvas + if (imgW > CanvasXSize) { clearX = imgW; } // image larger than canvas + else { clearX = CanvasXSize; } + if (imgH > CanvasYSize) { clearY = imgH; } // image larger than canvas + else { clearY = CanvasYSize; } + //Get Canvas Element + ctx = document.getElementById('canvas').getContext('2d'); + //Set Refresh Rate + return setInterval(draw, speed); +} + +function draw() { + //Clear Canvas + ctx.clearRect(0,0,clearX,clearY); + //If image is <= Canvas Size + if (imgW <= CanvasXSize) { + //reset, start from beginning + if (x > (CanvasXSize)) { x = 0; } + //draw aditional image + if (x > (CanvasXSize-imgW)) { ctx.drawImage(img,x-CanvasXSize+1,y,imgW,imgH); } + } + //If image is > Canvas Size + else { + //reset, start from beginning + if (x > (CanvasXSize)) { x = CanvasXSize-imgW; } + //draw aditional image + if (x > (CanvasXSize-imgW)) { ctx.drawImage(img,x-imgW+1,y,imgW,imgH); } + } + //draw image + ctx.drawImage(img,x,y,imgW,imgH); + //amount to move + x += dx; +} +</pre> + +<p>循環景色就是在下方的{{HTMLElement("canvas")}}中捲動，請注意其中的width和height和程式碼中的CanvasXZSize與CanvasYSize一樣。</p> + +<pre class="brush: html"><canvas id="canvas" width="800" height="200"></canvas></pre> + +<p><strong>Live sample</strong></p> + +<p>{{EmbedLiveSample("A_looping_panorama", "830", "230")}}</p> + +<h2 id="Other_examples" name="Other_examples">其他範例</h2> + +<dl> + <dt><a class="external" href="http://www.gartic.net/" title="http://www.gartic.net/">Gartic</a></dt> + <dd> + <p>多人繪圖遊戲</p> + </dd> + <dt><a class="external" href="http://www.abrahamjoffe.com.au/ben/canvascape/">Canvascape</a></dt> + <dd> + <p>第一人稱3D冒險遊戲</p> + </dd> + <dt><a href="/en-US/docs/Web/Guide/HTML/A_basic_ray-caster" title="/en-US/docs/Web/Guide/HTML/A_basic_ray-caster">A basic ray-caster</a></dt> + <dd>透過鍵盤控制動畫範例</dd> + <dt><a class="external" href="http://andrewwooldridge.com/canvas/canvasgame001/canvasgame002.html">canvas adventure</a></dt> + <dd> + <p>另一個透過鍵盤控制動畫範例</p> + </dd> + <dt><a class="external" href="http://www.blobsallad.se/">An interactive Blob</a></dt> + <dd>和Blob遊戲</dd> + <dt><a class="external" href="http://arapehlivanian.com/wp-content/uploads/2007/02/canvas.html">Flying through a starfield</a></dt> + <dd> + <p>飛越星河</p> + </dd> + <dt><a class="external" href="http://igrapher.com/" title="http://igrapher.com/">iGrapher</a></dt> + <dd> + <p>股票市場圖</p> + </dd> +</dl> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/JavaScript/Timers" title="/en-US/docs/JavaScript/Timers">JavaScript timers</a></li> + <li><a href="/en-US/docs/DOM/window.setInterval#A_little_framework" title="/en-US/docs/DOM/window.setInterval#A_little_framework"><code>setInterval</code> – A little framework</a></li> + <li><a href="/en-US/docs/JavaScript/Timers/Daemons" title="/en-US/docs/JavaScript/Timers/Daemons">JavaScript Daemons Management</a></li> + <li><a href="/en-US/docs/DOM/HTMLCanvasElement" title="/en-US/docs/DOM/HTMLCanvasElement">HTMLCanvasElement</a></li> +</ul> + +<p>{{PreviousNext("Web/Guide/HTML/Canvas_tutorial/Compositing", "Web/Guide/HTML/Canvas_tutorial/Optimizing_canvas")}}</p> diff --git a/files/zh-tw/web/api/canvas_api/tutorial/basic_usage/index.html b/files/zh-tw/web/api/canvas_api/tutorial/basic_usage/index.html new file mode 100644 index 0000000000..9d39027c96 --- /dev/null +++ b/files/zh-tw/web/api/canvas_api/tutorial/basic_usage/index.html @@ -0,0 +1,158 @@ +--- +title: Canvas 基本用途 +slug: Web/API/Canvas_API/Tutorial/Basic_usage +translation_of: Web/API/Canvas_API/Tutorial/Basic_usage +--- +<div>{{CanvasSidebar}} {{PreviousNext("Web/API/Canvas_API/Tutorial", "Web/API/Canvas_API/Tutorial/Drawing_shapes")}}</div> + +<div class="summary"> +<p>Let's start this tutorial by looking at the {{HTMLElement("canvas")}} {{Glossary("HTML")}} element itself. At the end of this page, you will know how to set up a canvas 2D context and have drawn a first example in your browser.</p> +</div> + +<h2 id="<canvas>_元素"><code><canvas></code> 元素</h2> + +<pre class="brush: html"><canvas id="tutorial" width="150" height="150"></canvas> +</pre> + +<p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">首先，先來看看 </span></font>{{HTMLElement("canvas")}}<font face="DejaVu Sans, sans-serif"><span lang="zh-TW">，它看起來有點像 </span></font>{{HTMLElement("img")}}<font face="DejaVu Sans, sans-serif"><span lang="zh-TW"> 元素，其中的差異點在於 </span></font><code><canvas></code><font face="DejaVu Sans, sans-serif"><span lang="zh-TW"> 沒有 </span></font><code>src</code><font face="DejaVu Sans, sans-serif"> <span lang="zh-TW">和</span> </font><code>alt</code><font face="DejaVu Sans, sans-serif"> <span lang="zh-TW">屬性，</span></font><code><canvas></code><font face="DejaVu Sans, sans-serif"><span lang="zh-TW"> 只有 </span></font>{{htmlattrxref("width", "canvas")}}<font face="DejaVu Sans, sans-serif"><span lang="zh-TW"> </span><span lang="zh-TW">與 </span></font>{{htmlattrxref("height", "canvas")}}<font face="DejaVu Sans, sans-serif"><span lang="zh-TW"> 這兩個屬性，這兩個屬性皆為非必須、能透過</span></font><a href="/en-US/docs/DOM" rel="internal" title="en/DOM"> DOM</a><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">屬性設定；若是沒有設定 </span></font><code>width</code><font face="DejaVu Sans, sans-serif"><span lang="zh-TW"> 和 </span></font><code>height</code><font face="DejaVu Sans, sans-serif"><span lang="zh-TW"> 屬性，畫布寬預設值為</span></font><strong><font face="DejaVu Sans, sans-serif"> </font>300 pixels</strong><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">、高預設值為<strong> </strong></span></font><strong>150 pixels</strong><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">，我們可以用 </span></font><a href="/en-US/docs/Web/CSS" rel="internal" title="en/CSS">CSS </a><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">強制設定元素尺寸，但當渲染時，影像會縮放以符合元素的尺寸。</span></font></p> + +<div class="note"> +<p style="margin-bottom: 0in;"><strong>Note:</strong><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">如果繪圖結果看起來有些扭曲，可以改試著用</span></font><font face="DejaVu Sans, sans-serif"><canvas></font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">自身的</span></font><font face="DejaVu Sans, sans-serif">width</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">和</span></font><font face="DejaVu Sans, sans-serif">height</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">屬性而不要用</span></font><font face="DejaVu Sans, sans-serif">CSS</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">來設定寬高。</span></font></p> +</div> + +<p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">幾乎所有</span></font><font face="DejaVu Sans, sans-serif">HTML</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">元素都有</span></font><font face="DejaVu Sans, sans-serif">id</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">屬性，</span></font><font face="DejaVu Sans, sans-serif"><canvas></font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">也不例外，為了方便於程式碼腳本找到需要的</span></font><font face="DejaVu Sans, sans-serif"><canvas></font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">，每次都設定</span></font><font face="DejaVu Sans, sans-serif">id</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">是一項不錯的作法。</span></font></p> + +<p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">如同一般的影像可以設定如邊界</span></font><font face="DejaVu Sans, sans-serif">(margin)</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">、邊框</span></font><font face="DejaVu Sans, sans-serif">(border)</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">、背景</span></font><font face="DejaVu Sans, sans-serif">(background)</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">等等，</span></font><font face="DejaVu Sans, sans-serif"><canvas></font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">元素一樣可以設定這些樣式，然而，這些樣式規則不會影響</span></font><font face="DejaVu Sans, sans-serif">canvas</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">實際繪圖，稍後我們會看到相關範例。當沒有套用樣式規定時，</span></font><font face="DejaVu Sans, sans-serif"><canvas></font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">會被初始成全透明。</span></font></p> + +<p style="margin-bottom: 0in;"> </p> + +<div id="section_2"> +<h3 id="錯誤替代內容(Fallback_content)"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">錯誤替代內容(</span></font>Fallback content)</h3> + +<p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">因為舊版瀏覽器</span></font><font face="DejaVu Sans, sans-serif">(</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">特別是</span></font><font face="DejaVu Sans, sans-serif">IE9</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">之前的</span></font><font face="DejaVu Sans, sans-serif">IE)</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">不支援</span></font><font face="DejaVu Sans, sans-serif">{<canvas>}</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">元素，我們應該為這些瀏覽器準備錯誤替代內容。</span></font></p> + +<p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">當不支援</span></font><font face="DejaVu Sans, sans-serif"><canvas></font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">的瀏覽器看到不認識的</span></font><font face="DejaVu Sans, sans-serif"><canvas></font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">時會忽略</span></font><font face="DejaVu Sans, sans-serif"><canvas></font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">，而此時在</span></font><font face="DejaVu Sans, sans-serif"><canvas></font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">下瀏覽器認識的替代內容則會被瀏覽器解析顯示，至於支援</span></font><font face="DejaVu Sans, sans-serif"><canvas></font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">的瀏覽器則是會正常解析</span></font><font face="DejaVu Sans, sans-serif"><canvas></font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">，忽略替代內容。</span></font></p> + +<p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">例如，我們可以準備一段</span></font><font face="DejaVu Sans, sans-serif">canvas</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">內容的說明文字或</span></font><font face="DejaVu Sans, sans-serif">canvas</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">繪圖完成後的靜態圖片，如下所示</span></font><font face="DejaVu Sans, sans-serif">:</font></p> + +<pre class="brush: html"><canvas id="stockGraph" width="150" height="150"> + current stock price: $3.15 +0.15 +</canvas> + +<canvas id="clock" width="150" height="150"> + <img src="images/clock.png" width="150" height="150" alt=""/> +</canvas> +</pre> + +<h6 id="sect1"> </h6> + +<h2 id="需要<canvas>標籤"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">需要</span></font><font face="DejaVu Sans, sans-serif"></canvas></font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">標籤</span></font></h2> + +<p style="margin-bottom: 0in;"><font face="DejaVu Sans"><span lang="zh-TW"><font face="DejaVu Sans, sans-serif">不像</font></span></font>{{HTMLElement("img")}}<font face="DejaVu Sans"><span lang="zh-TW"><font face="DejaVu Sans, sans-serif">元素，</font></span></font><font face="DejaVu Sans, sans-serif">{{HTMLElement("canvas")}}</font><font face="DejaVu Sans"><span lang="zh-TW"><font face="DejaVu Sans, sans-serif">元素必須要有</font></span></font><font face="DejaVu Sans, sans-serif"></canvas></font><font face="DejaVu Sans"><span lang="zh-TW"><font face="DejaVu Sans, sans-serif">結束標籤。</font></span></font></p> + +<p style="margin-bottom: 0in;"> </p> + +<div class="note"> +<p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">縱使早期</span></font><font face="DejaVu Sans, sans-serif">Apple</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">的</span></font><font face="DejaVu Sans, sans-serif">Safari</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">瀏覽器不需要結束標籤，但是基於規範，這是必須的，所以，為了相容性考量，應該要有結束標籤。</span></font><font face="DejaVu Sans, sans-serif">Safari 2.0</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">以前的版本會同時解析</span></font><font face="DejaVu Sans, sans-serif">canvas</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">以及替代內容，除非我們用</span></font><font face="DejaVu Sans, sans-serif">CSS</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">去遮蓋內容，不過幸運的是，現在已經沒有甚麼人在用這些舊版</span></font><font face="DejaVu Sans, sans-serif">Safari</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">。</span></font></p> +</div> + +<p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">如果不需要錯誤替代內容，簡單的</span></font><font face="DejaVu Sans, sans-serif"><canvas id="foo" ...></canvas></font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">便可以完全相容於所有支援的瀏覽器。</span></font></p> + +<p style="margin-bottom: 0in;"> </p> + +<h2 id="渲染環境(rendering_context)"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">渲染環境</span></font>(rendering context)</h2> + +<p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif">{{HTMLElement("canvas")}}</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">產生一個固定大小的繪圖畫布，這個畫布上有一或多個</span></font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">渲染環境</span></font><font face="DejaVu Sans, sans-serif">(rendering context)，我們</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">可以用</span></font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">渲染環境</span></font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">來產生或操作顯示內容的渲染環境</span></font><font face="DejaVu Sans, sans-serif">(rendering context)</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">。</span></font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW"><font face="DejaVu Sans, sans-serif">不同</font>環境</span></font><font face="DejaVu Sans, sans-serif">(context)</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">可能會提供不同型態的渲染方式，好比說</span></font><a href="/en-US/docs/Web/WebGL" title="/en-US/docs/Web/WebGL">WebGL</a><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">使用</span></font><a class="external" href="http://www.khronos.org/opengles/" rel="external" title="http://en.wikipedia.org/wiki/OpenGL_ES">OpenGL ES</a><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">的</span></font><font face="DejaVu Sans, sans-serif">3D</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">環境</span></font><font face="DejaVu Sans, sans-serif">(context)，</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">而這裡我們主要將討論</span></font><font face="DejaVu Sans, sans-serif">2D</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">渲染環境</span></font><font face="DejaVu Sans, sans-serif">(rendering context)</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">。</span></font></p> + +<p style="margin-bottom: 0in;"><font face="DejaVu Sans"><span lang="zh-TW"><font face="DejaVu Sans, sans-serif">一開始</font></span></font><font face="DejaVu Sans, sans-serif">canvas</font><font face="DejaVu Sans"><span lang="zh-TW"><font face="DejaVu Sans, sans-serif">為空白，程式碼腳本需要先存取渲染環境，在上面繪圖，然後才會顯現影像。</font></span></font>{{HTMLElement("canvas")}} <font face="DejaVu Sans"><span lang="zh-TW"><font face="DejaVu Sans, sans-serif">素有一個方法</font></span></font><font face="DejaVu Sans, sans-serif">(</font><a href="/en-US/docs/Web/API/HTMLCanvasElement#Methods" title="/en-US/docs/Web/API/HTMLCanvasElement#Methods">method</a><font face="DejaVu Sans, sans-serif">)</font><font face="DejaVu Sans"><span lang="zh-TW"><font face="DejaVu Sans, sans-serif">叫</font></span></font><font face="DejaVu Sans, sans-serif">getContext()</font><font face="DejaVu Sans"><span lang="zh-TW"><font face="DejaVu Sans, sans-serif">，透過此方法可以取得渲染環境及其繪圖函數</font></span></font><font face="DejaVu Sans, sans-serif">(function)</font><font face="DejaVu Sans"><span lang="zh-TW"><font face="DejaVu Sans, sans-serif">；</font></span></font><font face="DejaVu Sans, sans-serif">getContext()</font><font face="DejaVu Sans"><span lang="zh-TW"><font face="DejaVu Sans, sans-serif">輸入參數只有渲染環境類型一項，像本教學所討論的</font></span></font><font face="DejaVu Sans, sans-serif">2D</font><font face="DejaVu Sans"><span lang="zh-TW"><font face="DejaVu Sans, sans-serif">繪圖，就是輸入”</font></span></font><font face="DejaVu Sans, sans-serif">2d”</font><font face="DejaVu Sans"><span lang="zh-TW"><font face="DejaVu Sans, sans-serif">。</font></span></font></p> + +<pre class="brush: js">var canvas = document.getElementById('tutorial'); +var ctx = canvas.getContext('2d'); +</pre> + +<p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">上面第一行先呼叫</span></font>{{domxref("document.getElementById()")}}<font face="DejaVu Sans, sans-serif"><span lang="zh-TW">來取得</span></font>{{HTMLElement("canvas")}}<font face="DejaVu Sans, sans-serif"><span lang="zh-TW">元素，一旦取得元素後，便可以用其</span></font><font face="DejaVu Sans, sans-serif">getContext()</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">取得渲染環境。</span></font></p> + +<p style="margin-bottom: 0in;"> </p> + +<div id="section_5"> +<h2 id="支援性檢查"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">支援性檢查</span></font></h2> + +<p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">替代內容會被不支援</span></font>{{HTMLElement("canvas")}}.<font face="DejaVu Sans, sans-serif"><span lang="zh-TW">的瀏覽器所顯示。程式碼腳本也可以利用檢查</span></font><font face="DejaVu Sans, sans-serif">getContext()</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">方法是否存在來檢查是否支援</span></font><font face="DejaVu Sans, sans-serif"><canvas></font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">，我們可以修改上面例子成如下</span></font><font face="DejaVu Sans, sans-serif">:</font></p> + +<pre class="brush: js">var canvas = document.getElementById('tutorial'); + +if (canvas.getContext){ + var ctx = canvas.getContext('2d'); + // drawing code here +} else { + // canvas-unsupported code here +} +</pre> +</div> +</div> + +<h6 id="sect2"> </h6> + +<h2 id="一個範本"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">一個範本</span></font></h2> + +<p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">這裡是一個最簡單的範本，之後就是我們範例的起始點。</span></font></p> + +<pre class="brush: html"><html> + <head> + <title>Canvas tutorial</title> + <script type="text/javascript"> + function draw(){ + var canvas = document.getElementById('tutorial'); + if (canvas.getContext){ + var ctx = canvas.getContext('2d'); + } + } + </script> + <style type="text/css"> + canvas { border: 1px solid black; } + </style> + </head> + <body onload="draw();"> + <canvas id="tutorial" width="150" height="150"></canvas> + </body> +</html> +</pre> + +<p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">一旦網頁載入完成後，程式碼會呼叫</span></font><font face="DejaVu Sans, sans-serif">draw()</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">函數</span></font><font face="DejaVu Sans, sans-serif">(</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">這是利用</span></font><font face="DejaVu Sans, sans-serif">document</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">上的</span></font><font face="DejaVu Sans, sans-serif">load</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">事件完成</span></font><font face="DejaVu Sans, sans-serif">)</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">，這類</span></font><font face="DejaVu Sans, sans-serif">draw()</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">函數也可以透過</span></font>{{domxref("window.setTimeout()")}}<font face="DejaVu Sans, sans-serif">, </font>{{domxref("window.setInterval()")}}<font face="DejaVu Sans, sans-serif"><span lang="zh-TW">或其他事件處理函數來呼叫，只要呼叫的時間點是在網頁載入完後。</span></font></p> + +<p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">這是我們的範本實際看起來的樣子</span></font><font face="DejaVu Sans, sans-serif">:</font></p> + +<p>{{EmbedLiveSample("A_skeleton_template", 160, 160)}}</p> + +<h2 id="一個簡單的範例"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">一個簡單的範例</span></font></h2> + +<p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">首先，讓我們先來畫兩個相交的正方形，其中一個正方形有</span></font><font face="DejaVu Sans, sans-serif">alpha</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">透明值，之後我們會說明這是如何達成的。</span></font></p> + +<pre class="brush: html"><html> + <head> + <script type="application/javascript"> + function draw() { + var canvas = document.getElementById("canvas"); + if (canvas.getContext) { + var ctx = canvas.getContext("2d"); + + ctx.fillStyle = "rgb(200,0,0)"; + ctx.fillRect (10, 10, 55, 50); + + ctx.fillStyle = "rgba(0, 0, 200, 0.5)"; + ctx.fillRect (30, 30, 55, 50); + } + } + </script> + </head> + <body onload="draw();"> + <canvas id="canvas" width="150" height="150"></canvas> + </body> +</html> +</pre> + +<p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">本範例的結果如下</span></font><font face="DejaVu Sans, sans-serif">:</font></p> + +<p>{{EmbedLiveSample("A_simple_example", 160, 160, "https://mdn.mozillademos.org/files/228/canvas_ex1.png")}}</p> + +<p>{{PreviousNext("Web/Guide/HTML/Canvas_tutorial", "Web/Guide/HTML/Canvas_tutorial/Drawing_shapes")}}</p> diff --git a/files/zh-tw/web/api/canvas_api/tutorial/compositing/index.html b/files/zh-tw/web/api/canvas_api/tutorial/compositing/index.html new file mode 100644 index 0000000000..e5453c93a5 --- /dev/null +++ b/files/zh-tw/web/api/canvas_api/tutorial/compositing/index.html @@ -0,0 +1,207 @@ +--- +title: 合成效果 +slug: Web/API/Canvas_API/Tutorial/Compositing +translation_of: Web/API/Canvas_API/Tutorial/Compositing +--- +<div>{{CanvasSidebar}} {{PreviousNext("Web/API/Canvas_API/Tutorial/Transformations", "Web/API/Canvas_API/Tutorial/Basic_animations")}}</div> + +<p>在前述的範例中，新繪製的圖形總會覆蓋在之前的圖形上，對大多數情況來說這相當正常，不過它也限制了圖形繪製的順序。其實我們可以透過 globalCompositeOperation 屬性來改變這項預設行為。</p> + +<h2 id="globalCompositeOperation" name="globalCompositeOperation"><code>globalCompositeOperation</code></h2> + +<p>利用 globalCompositeOperation，我們可以將新圖形繪製在舊圖形之下、遮蓋部分區域、清除畫布部分區域 (不同於 clearRect() 函式只能清除矩形區域)。</p> + +<dl> + <dt><code>globalCompositeOperation = <em>type</em></code></dt> + <dt>type 字串可指定為以下 12 種合成設定之一，每一種合成設定均將套用到新繪製的圖形上。</dt> +</dl> + +<div class="note"> +<p><strong>Note:</strong> 下列圖例的藍色矩形是舊圖形，紅色圓形是新圖形。</p> +</div> + +<table style="width: 100%;"> + <tbody> + <tr> + <td style="padding: 5px; vertical-align: top;"> + <p><strong>source-over</strong> 預設值。將新圖形畫在舊圖形之上。</p> + </td> + <td style="padding: 5px; vertical-align: top;"> + <p><img alt="Image:Canvas_composite_srcovr.png" class="internal" src="https://mdn.mozillademos.org/files/220/Canvas_composite_srcovr.png"></p> + </td> + <td style="padding: 5px; vertical-align: top;"> + <p><strong>destination-over</strong><br> + 將新圖形畫在舊圖形之下。</p> + </td> + <td style="padding: 5px; vertical-align: top;"> + <p><img alt="Image:Canvas_composite_destovr.png" class="internal" src="https://mdn.mozillademos.org/files/215/Canvas_composite_destovr.png"></p> + </td> + </tr> + <tr> + <td style="padding: 5px; vertical-align: top;"> + <p><strong>source-in</strong><br> + 只保留新、舊圖形重疊的新圖形區域，其餘皆變為透明。</p> + </td> + <td style="padding: 5px; vertical-align: top;"> + <p><img alt="Image:Canvas_composite_srcin.png" class="internal" src="https://mdn.mozillademos.org/files/218/Canvas_composite_srcin.png"></p> + </td> + <td style="padding: 5px; vertical-align: top;"> + <p><strong>destination-in</strong><br> + 只保留新、舊圖形重疊的舊圖形區域，其餘皆變為透明。</p> + </td> + <td style="padding: 5px; vertical-align: top;"> + <p><img alt="Image:Canvas_composite_destin.png" class="internal" src="https://mdn.mozillademos.org/files/213/Canvas_composite_destin.png"></p> + </td> + </tr> + <tr> + <td style="padding: 5px; vertical-align: top;"> + <p><strong>source-out</strong><br> + 只保留新、舊圖形非重疊的新圖形區域，其餘皆變為透明。</p> + </td> + <td style="padding: 5px; vertical-align: top;"> + <p><img alt="Image:Canvas_composite_srcout.png" class="internal" src="https://mdn.mozillademos.org/files/219/Canvas_composite_srcout.png"></p> + </td> + <td style="padding: 5px; vertical-align: top;"> + <p><strong>destination-out</strong><br> + 只保留新、舊圖形非重疊的舊圖形區域，其餘皆變為透明。</p> + </td> + <td style="padding: 5px; vertical-align: top;"> + <p><img alt="Image:Canvas_composite_destout.png" class="internal" src="https://mdn.mozillademos.org/files/214/Canvas_composite_destout.png"></p> + </td> + </tr> + <tr> + <td style="padding: 5px; vertical-align: top;"> + <p><strong>source-atop</strong><br> + 新圖形只繪製在新、舊圖形重疊的新圖形區域，然後蓋在舊圖形之上。</p> + </td> + <td style="padding: 5px; vertical-align: top;"> + <p><img alt="Image:Canvas_composite_srcatop.png" class="internal" src="https://mdn.mozillademos.org/files/217/Canvas_composite_srcatop.png"></p> + </td> + <td style="padding: 5px; vertical-align: top;"> + <p><strong>destination-atop</strong><br> + 舊圖形只保留在新、舊圖形重疊的舊圖形區域，然後蓋在新圖形之上。</p> + </td> + <td style="padding: 5px; vertical-align: top;"> + <p><img alt="Image:Canvas_composite_destatop.png" class="internal" src="https://mdn.mozillademos.org/files/212/Canvas_composite_destatop.png"></p> + </td> + </tr> + <tr> + <td style="padding: 5px; vertical-align: top;"> + <p><strong>lighter</strong><br> + 新舊圖形重疊區域的顏色，由新、舊圖形的顏色碼相加而得。</p> + </td> + <td style="padding: 5px; vertical-align: top;"> + <p><img alt="Image:Canvas_composite_lighten.png" class="internal" src="https://mdn.mozillademos.org/files/216/Canvas_composite_lighten.png"></p> + </td> + <td style="padding: 5px; vertical-align: top;"> + <p><strong>darker</strong> {{obsolete_inline}}</p> + + <p>新舊圖形重疊區域的顏色，由新、舊圖形的顏色碼相減而得。此屬性值已經從畫布規格中移除了，不再支援。</p> + </td> + <td style="padding: 5px; vertical-align: top;"> + <p><img alt="Image:Canvas_composite_darken.png" class="internal" src="https://mdn.mozillademos.org/files/211/Canvas_composite_darken.png"></p> + </td> + </tr> + <tr> + <td style="padding: 5px; vertical-align: top;"> + <p><strong>xor</strong><br> + 新舊圖形重疊區域設為透明。</p> + </td> + <td style="padding: 5px; vertical-align: top;"> + <p><img alt="Image:Canvas_composite_xor.png" class="internal" src="https://mdn.mozillademos.org/files/221/Canvas_composite_xor.png"></p> + </td> + <td style="padding: 5px; vertical-align: top;"> + <p><strong>copy</strong><br> + 移除其他圖形，只保留新圖形。</p> + </td> + <td style="padding: 5px; vertical-align: top;"> + <p><img alt="Image:Canvas_composite_copy.png" class="internal" src="https://mdn.mozillademos.org/files/210/Canvas_composite_copy.png"></p> + </td> + </tr> + </tbody> +</table> + +<p>這裡有這些構圖組合的<a href="/en-US/docs/Web/Guide/HTML/Canvas_tutorial/Compositing/Example" title="/en-US/docs/Web/Guide/HTML/Canvas_tutorial/Compositing/Example">實際範例</a>，<a href="https://mdn.mozillademos.org/en-US/docs/Web/Guide/HTML/Canvas_tutorial/Compositing/Example$samples/Compositing_example" title="https://mdn.mozillademos.org/en-US/docs/Web/Guide/HTML/Canvas_tutorial/Compositing/Example$samples/Compositing_example">輸出結果</a>在此。</p> + +<h2 id="Clipping_paths" name="Clipping_paths">裁剪路徑</h2> + +<p><img alt="" class="internal" src="https://mdn.mozillademos.org/files/209/Canvas_clipping_path.png" style="float: right;">裁剪路徑就像是一般畫布圖形繪圖，但就如同遮罩一樣，會蓋掉不需要的部分，如右圖所示。紅邊星星是我們的裁剪路徑，在路徑區域以外部分都不會出現在畫布上。</p> + +<p>和上述 globalCompositeOperation 相比，可以發現 source-in 和 source-atop 這兩種構圖組合所達到的效果，和裁剪路徑類似，而其中最大差異在於裁剪路徑不需加入新圖形，消失的部分也不會出現在畫布上，所以，如果想要限定繪圖區域，裁剪路徑會是更理想的作法。</p> + +<p>在<a href="/en-US/docs/Web/Guide/HTML/Canvas_tutorial/Drawing_shapes#Drawing_paths" title="Web/Guide/HTML/Canvas_tutorial/Drawing_shapes#Drawing_paths">繪畫圖形</a>一章中，我們只提到 stroke() 和 fill() 函式，但其實還有第三個函式，那就是 clip() 函式。</p> + +<dl> + <dt><code>clip()</code></dt> + <dd>轉換目前繪圖路徑為裁剪路徑。</dd> +</dl> + +<p>呼叫 clip() 除了會替代 closePath() 來關閉路徑之外，還會轉換目前填滿或勾勒繪圖路徑為裁剪路徑。</p> + +<p> {{HTMLElement("canvas")}} 畫布預設有一個等同於本身大小的裁剪路徑，等同於無裁剪效果。</p> + +<h3 id="A_clip_example" name="A_clip_example"><code>clip</code> 範例</h3> + +<p>本範例使用了圓形的裁剪路徑，來限定畫星星時的繪圖區域。</p> + +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + ctx.fillRect(0,0,150,150); + ctx.translate(75,75); + + // Create a circular clipping path + ctx.beginPath(); + ctx.arc(0,0,60,0,Math.PI*2,true); + ctx.clip(); + + // draw background + var lingrad = ctx.createLinearGradient(0,-75,0,75); + lingrad.addColorStop(0, '#232256'); + lingrad.addColorStop(1, '#143778'); + + ctx.fillStyle = lingrad; + ctx.fillRect(-75,-75,150,150); + + // draw stars + for (var j=1;j<50;j++){ + ctx.save(); + ctx.fillStyle = '#fff'; + ctx.translate(75-Math.floor(Math.random()*150), + 75-Math.floor(Math.random()*150)); + drawStar(ctx,Math.floor(Math.random()*4)+2); + ctx.restore(); + } + +} + +function drawStar(ctx,r){ + ctx.save(); + ctx.beginPath() + ctx.moveTo(r,0); + for (var i=0;i<9;i++){ + ctx.rotate(Math.PI/5); + if(i%2 == 0) { + ctx.lineTo((r/0.525731)*0.200811,0); + } else { + ctx.lineTo(r,0); + } + } + ctx.closePath(); + ctx.fill(); + ctx.restore(); +} +</pre> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" width="150" height="150"></canvas></pre> + +<pre class="brush: js">draw();</pre> +</div> + +<p>一開始我們先畫了一個黑色矩形作為畫布背景，然後移動畫布原點到中央，接著我們繪製弧線並呼叫 clip()，藉以建立圓形的裁剪路徑。畫布儲存狀態亦可儲存裁剪路徑。若要保留原本的裁剪路徑，則可於繪製新的裁剪路徑之前，先行儲存畫布狀態。</p> + +<p>繪製裁剪路徑之後，所產生的所有圖形都只會出現在路徑以內，從後來繪製的漸層背景中可看出此特性。我們用自訂的 drawStar() 函數產生 50 個隨機散佈、大小不一的星星。這些星星同樣只會出現在裁剪路徑的範圍之內。</p> + +<p>{{EmbedLiveSample("A_clip_example", "180", "180", "https://mdn.mozillademos.org/files/208/Canvas_clip.png")}}</p> + +<p>{{PreviousNext("Web/Guide/HTML/Canvas_tutorial/Transformations", "Web/Guide/HTML/Canvas_tutorial/Basic_animations")}}</p> diff --git a/files/zh-tw/web/api/canvas_api/tutorial/drawing_shapes/index.html b/files/zh-tw/web/api/canvas_api/tutorial/drawing_shapes/index.html new file mode 100644 index 0000000000..96fe2b9615 --- /dev/null +++ b/files/zh-tw/web/api/canvas_api/tutorial/drawing_shapes/index.html @@ -0,0 +1,551 @@ +--- +title: 繪製圖形 +slug: Web/API/Canvas_API/Tutorial/Drawing_shapes +translation_of: Web/API/Canvas_API/Tutorial/Drawing_shapes +--- +<div>{{CanvasSidebar}} {{PreviousNext("Web/API/Canvas_API/Tutorial/Basic_usage", "Web/API/Canvas_API/Tutorial/Applying_styles_and_colors")}}</div> + +<p id="網格(Grid)">網格(Grid)</p> + +<p><img alt="" class="internal" src="https://mdn.mozillademos.org/files/224/Canvas_default_grid.png" style="float: right; height: 220px; width: 220px;">在開始繪圖前，我們必須先了解畫布 (canvas) 網格，或著是說座標空間。在前一頁教學中的 HTML 範本有一個寬150 pixels (像素)、高150 pixels 的畫布。如右圖，你在畫布預設網格上繪圖，網格上 1 單位相當於畫布上 1 pixel，網格的原點 (座標 (0, 0) ) 坐落於左上角，所有元素定位皆相對於此左上角原點，所以藍色方塊的位置為從左往右推 x pixels、從上往下推 y pixels (亦即座標 (x, y) )。現在我們先專注在預設設定上，之後我們會看到如何轉換原點位置、旋轉網格以及縮放網格。</p> + +<p> </p> + +<p> </p> + +<p> </p> + +<h2 id="畫矩形">畫矩形</h2> + +<p>不同於<a href="/en-US/docs/SVG" rel="internal" title="en/SVG">SVG</a>，{{HTMLElement("canvas")}}只支援一種原始圖形，矩形。所有的圖形都必須由一或多個繪圖路徑構成，而我們正好有一些繪圖路徑函數可以讓我們畫出複雜的圖形。</p> + +<div id="section_3"> +<p>首先來看看矩形，共有三個矩形繪圖函數:</p> + +<dl> + <dt><code>fillRect(<em>x</em>, <em>y</em>, <em>width</em>, <em>height</em>)</code></dt> + <dd>畫出一個填滿的矩形。</dd> + <dt><code>strokeRect(<em>x</em>, <em>y</em>, <em>width</em>, <em>height</em>)</code></dt> + <dd>畫出一個矩形的邊框</dd> + <dt><code>clearRect(<em>x</em>, <em>y</em>, <em>width</em>, <em>height</em>)</code></dt> + <dd>清除指定矩形區域內的內容，使其變為全透明。</dd> +</dl> + +<p>這三個函數都接受一樣的參數: x, y代表從原點出發的座標位置，width, height代表矩形的寬高。</p> + +<h3 id="矩形範例">矩形範例</h3> + +<div class="hidden"> +<pre class="brush: html"><html> + <body onload="draw();"> + <canvas id="canvas" width="150" height="150"></canvas> + </body> +</html> +</pre> +</div> + +<pre class="brush: js">function draw() { + var canvas = document.getElementById('canvas'); + if (canvas.getContext) { + var ctx = canvas.getContext('2d'); + + ctx.fillRect(25,25,100,100); + ctx.clearRect(45,45,60,60); + ctx.strokeRect(50,50,50,50); + } +}</pre> + +<p>本例結果如下:</p> + +<p>{{EmbedLiveSample("Rectangular_shape_example", 160, 160, "https://mdn.mozillademos.org/files/245/Canvas_rect.png")}}</p> + +<p>fillRect()函數畫出一個寬高都100 pixels的矩形，clearRect()函數清除中央60 x 60 pixels大的正方形區域，接著strokeRect()在被清除區域內畫上一個50 x 50 pixels的矩形邊框。</p> + +<p>之後我們會看到另外兩種代替clearRect()的方法，還有如何改變圖形顏色與筆畫樣式。</p> + +<p>不像之後會看到的路徑繪圖函數，這三個函數會立即在畫布上畫出矩形。</p> + +<h2 id="路徑繪製">路徑繪製</h2> + +<p>使用路徑 (path) 來畫圖形需要多一點步驟，一開始先產生路徑，然後用繪圖指令畫出路徑，然後再結束路徑，一旦路徑產生後便可以用畫筆或填滿方式來渲染生成，這裡是一些可用函數:</p> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.beginPath", "beginPath()")}}</dt> + <dd>產生一個新路徑，產生後再使用繪圖指令來設定路徑。</dd> + <dt>{{domxref("CanvasRenderingContext2D.closePath", "closePath()")}}</dt> + <dd>閉合路徑好讓新的繪圖指令來設定路徑。</dd> + <dt><a href="https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D#Paths">路徑 API</a></dt> + <dd>路徑 API，這些 API 便是繪圖指令</dd> +</dl> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.stroke", "stroke()")}}</dt> + <dd>畫出圖形的邊框。</dd> + <dt>{{domxref("CanvasRenderingContext2D.fill", "fill()")}}</dt> + <dd>填滿路徑內容區域來產生圖形。</dd> +</dl> + +<p>第一步呼叫 beginPath() 產生一個路徑，表面下，路徑會被存在一個次路徑 (sub-path) 清單中，例如直線、曲線等，這些次路徑集合起來就形成一塊圖形。每一次呼叫這個方法，次路徑清單就會被重設，然後我們便能夠畫另一個新圖形。</p> + +<div class="note"><strong>Note:</strong> 當目前路徑為空(例如接著呼叫beginPath()完後)或是在一個新畫布上，不論為何，第一個路徑繪圖指令總是moveTo()；因為每當重設路徑後，你幾乎都會需要設定繪圖起始點。</div> + +<p>第二步是呼叫各式方法來實際設定繪圖路徑，稍後我們將會介紹這部分。</p> + +<p>第三步，也是非必要的一步，就是呼叫closePath()。這個方法會在現在所在點到起始點間畫一條直線以閉合圖形，如果圖形已經閉合或是只含一個點，這個方法不會有任何效果。</p> + +<div class="note"><strong>Note:</strong> 當呼叫fill()，任何開放的圖形都會自動閉合，所以不需要再呼叫closePath()，但是stroke()並非如此。</div> + +<h3 id="畫一個三角形">畫一個三角形</h3> + +<p>這是一個畫出三角形的程式碼範例。</p> + +<div class="hidden"> +<pre class="brush: html"><html> + <body onload="draw();"> + <canvas id="canvas" width="150" height="150"></canvas> + </body> +</html> +</pre> +</div> + +<pre class="brush: js">function draw() { + var canvas = document.getElementById('canvas'); + if (canvas.getContext){ + var ctx = canvas.getContext('2d'); + + ctx.beginPath(); + ctx.moveTo(75,50); + ctx.lineTo(100,75); + ctx.lineTo(100,25); + ctx.fill(); + } +} +</pre> + +<p>結果如下:</p> + +<p>{{EmbedLiveSample("Drawing_a_triangle", 110, 110, "https://mdn.mozillademos.org/files/9847/triangle.png")}}</p> + +<h3 id="移動畫筆">移動畫筆</h3> + +<p>moveTo()是一個很有用的函數，moveTo()不會畫任何圖形，但卻是上述路徑清單的一部分，這大概有點像是把筆從紙上一點提起來，然後放到另一個點。</p> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.moveTo", "moveTo(x, y)")}}</dt> + <dd>移動畫筆到指定的(x, y)座標點</dd> +</dl> + +<p>當初始化畫布或是呼叫beginPath()，通常會想要使用moveTo()來指定起始點，我們可以用moveTo()畫不連結的路徑，看一下笑臉圖範例，圖中紅線即為使用到moveTo()的位置。</p> + +<p>你可以拿下面的程式碼，放進先前的draw()函數，自己試試看效果。</p> + +<div class="hidden"> +<pre class="brush: html"><html> + <body onload="draw();"> + <canvas id="canvas" width="150" height="150"></canvas> + </body> +</html> +</pre> +</div> + +<pre class="brush: js">function draw() { + var canvas = document.getElementById('canvas'); + if (canvas.getContext){ + var ctx = canvas.getContext('2d'); + + ctx.beginPath(); + ctx.arc(75,75,50,0,Math.PI*2,true); // Outer circle + ctx.moveTo(110,75); + ctx.arc(75,75,35,0,Math.PI,false); // Mouth (clockwise) + ctx.moveTo(65,65); + ctx.arc(60,65,5,0,Math.PI*2,true); // Left eye + ctx.moveTo(95,65); + ctx.arc(90,65,5,0,Math.PI*2,true); // Right eye + ctx.stroke(); + } +} +</pre> + +<p>結果如下:</p> + +<p>{{EmbedLiveSample("Moving_the_pen", 160, 160, "https://mdn.mozillademos.org/files/252/Canvas_smiley.png")}}</p> + +<p>移除moveTo()便可以看到線條連結起來。</p> + +<div class="note"> +<p><strong>Note:</strong> 有關arc()，請參照下方 {{anch("Arcs")}} .</p> +</div> + +<h3 id="線條">線條</h3> + +<p>用lineTo()方法畫直線。</p> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.lineTo", "lineTo(x, y)")}}</dt> + <dd>從目前繪圖點畫一條直線到指定的(x, y)座標點。</dd> +</dl> + +<p>本方法接受x, y參數作為線條結束點的座標位置，至於起始點則視前一個繪圖路徑，由前一個繪圖路徑的結束點作為起始點，當然，起始點也可以用moveTo()方法來變更。</p> + +<p>下面畫兩個三角形，一個填滿，一個空心。</p> + +<div class="hidden"> +<pre class="brush: html"><html> + <body onload="draw();"> + <canvas id="canvas" width="150" height="150"></canvas> + </body> +</html> +</pre> +</div> + +<pre class="brush: js">function draw() { + var canvas = document.getElementById('canvas'); + if (canvas.getContext){ + var ctx = canvas.getContext('2d'); + + // Filled triangle + ctx.beginPath(); + ctx.moveTo(25,25); + ctx.lineTo(105,25); + ctx.lineTo(25,105); + ctx.fill(); + + // Stroked triangle + ctx.beginPath(); + ctx.moveTo(125,125); + ctx.lineTo(125,45); + ctx.lineTo(45,125); + ctx.closePath(); + ctx.stroke(); + } +} +</pre> + +<p>從呼叫beginPath()起始一個新圖形路徑，然後用moveTo()移到我們想要的起始點，然後再畫兩條線形成三角形的兩邊。</p> + +<p>{{EmbedLiveSample("Lines", 160, 160, "https://mdn.mozillademos.org/files/238/Canvas_lineTo.png")}}</p> + +<p>我們可以看到填滿(fill)三角形和勾勒(stroke)三角形的區別；當填滿時，圖形會自動閉合，不過勾勒則不會，所以如果沒有呼叫closePaht()的話，只會畫出兩條線而非三角形。</p> + +<h3 id="弧形">弧形</h3> + +<p>用arc()方法來畫弧形或圓形。雖然也可以用arcTo()，但這個方法比較不可靠，所以這裡我們不討論arcTo()。</p> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.arc", "arc(x, y, radius, startAngle, endAngle, anticlockwise)")}}</dt> + <dd>畫一個弧形</dd> +</dl> + +<p>本方法接受五個參數: x, y代表圓心座標點，radius代表半徑，startAngle, endAngle分別代表沿著弧形曲線上的起始點與結束點的弧度，弧度測量是相對於x軸，anticlockwise為true代表逆時針作圖、false代表順時針作圖。</p> + +<div class="note"> +<p><strong>Note</strong>: arc()方法用的是弧度(radians)而非角度(degrees)，如果要在弧度與角度間換算，可以利用以下javascript程式碼: radians = (Math.PI/180) * degrees.</p> +</div> + +<p>以下例子比較複雜，它會畫出12個不同的弧形。</p> + +<p>兩個for迴圈走一遍弧形圖列的列跟行，每一個弧形由呼叫beginPath()開始新的繪圖路徑，為了清楚，我們在程式範例中用變數儲存參數，你不一定要這麼做。</p> + +<p>x, y座標點的部分應該相當淺顯，radius和startAngle是定值，endAngle從180度(半圓)開始，然後每一行增加90度，最後一行便會形成一個完整的圓。</p> + +<p>第1, 3列的anticlockwise 為false，所以會順時針作圖，2, 4列的anticlockwise 為true，所以會逆時針作圖。最後的if決定下半部是用填滿圖形，上半部是勾勒圖形。</p> + +<div class="hidden"> +<pre class="brush: html"><html> + <body onload="draw();"> + <canvas id="canvas" width="150" height="200"></canvas> + </body> +</html> +</pre> +</div> + +<pre class="brush: js">function draw() { + var canvas = document.getElementById('canvas'); + if (canvas.getContext){ + var ctx = canvas.getContext('2d'); + + for(var i=0;i<4;i++){ + for(var j=0;j<3;j++){ + ctx.beginPath(); + var x = 25+j*50; // x coordinate + var y = 25+i*50; // y coordinate + var radius = 20; // Arc radius + var startAngle = 0; // Starting point on circle + var endAngle = Math.PI+(Math.PI*j)/2; // End point on circle + var anticlockwise = i%2==0 ? false : true; // clockwise or anticlockwise + + ctx.arc(x, y, radius, startAngle, endAngle, anticlockwise); + + if (i>1){ + ctx.fill(); + } else { + ctx.stroke(); + } + } + } + } +} +</pre> +{{EmbedLiveSample("Arcs", 160, 210, "https://mdn.mozillademos.org/files/204/Canvas_arc.png")}} + +<h3 id="貝茲曲線(Bezier_curve)與二次曲線(quadratic_curve)">貝茲曲線(Bezier curve)與二次曲線(quadratic curve)</h3> + +<p>二次與三次<a href="http://en.wikipedia.org/wiki/B%C3%A9zier_curve" title="http://en.wikipedia.org/wiki/B%C3%A9zier_curve"><span class="external">貝茲曲線(Bézier curves</span>)</a>是另一種可用來構成複雜有機圖形的路徑。</p> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.quadraticCurveTo", "quadraticCurveTo(cp1x, cp1y, x, y)")}}</dt> + <dd>從目前起始點畫一條二次貝茲曲線到x, y指定的終點，控制點由cp1x, cp1y指定。</dd> + <dt>{{domxref("CanvasRenderingContext2D.bezierCurveTo", "bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y)")}}</dt> + <dd>從目前起始點畫一條三次貝茲曲線到x, y指定的終點，控制點由(cp1x, cp1y)和(cp2x, cp2y)指定。</dd> +</dl> + +<p><img alt="" class="internal" src="https://mdn.mozillademos.org/files/223/Canvas_curves.png" style="float: right; height: 190px; width: 190px;">二次和三次的差別可以從右圖看出；貝茲曲線的起始和終點以藍點標示，其中二次貝茲曲線只有一個控制點(如紅點標示)而三次貝茲曲線有兩個控制點。</p> + +<p>二次和三次貝茲曲線都用x, y參數定義終點座標，然後用cp1x, xp1y定義第一個控制點座標、cp2x, xp2y定義第二個控制點座標。</p> + +<p>用二次和三次貝茲曲線作圖相當具有挑戰性，因為不像使用 Adobe illustrator 的向量繪圖軟體，我們在繪圖時無法即時看到繪圖狀況，所以畫複雜的圖形十分困難。下面的範例我們畫了一些圖形，如果你有時間與耐心，可以畫出更複雜的圖形。</p> + +<h4 id="二次貝茲曲線">二次貝茲曲線</h4> + +<p>本例用了數個二次貝茲曲線畫了一個會話框。</p> + +<div class="hidden"> +<pre class="brush: html"><html> + <body onload="draw();"> + <canvas id="canvas" width="150" height="150"></canvas> + </body> +</html> +</pre> +</div> + +<pre class="brush: js">function draw() { + var canvas = document.getElementById('canvas'); + if (canvas.getContext) { + var ctx = canvas.getContext('2d'); + + // Quadratric curves example + ctx.beginPath(); + ctx.moveTo(75,25); + ctx.quadraticCurveTo(25,25,25,62.5); + ctx.quadraticCurveTo(25,100,50,100); + ctx.quadraticCurveTo(50,120,30,125); + ctx.quadraticCurveTo(60,120,65,100); + ctx.quadraticCurveTo(125,100,125,62.5); + ctx.quadraticCurveTo(125,25,75,25); + ctx.stroke(); + } +} +</pre> + +<p>{{EmbedLiveSample("Quadratic_Bezier_curves", 160, 160, "https://mdn.mozillademos.org/files/243/Canvas_quadratic.png")}}</p> + +<h4 id="三次貝茲曲線">三次貝茲曲線</h4> + +<p>這個範例畫了一個愛心。</p> + +<div class="hidden"> +<pre class="brush: html"><html> + <body onload="draw();"> + <canvas id="canvas" width="150" height="150"></canvas> + </body> +</html> +</pre> +</div> + +<pre class="brush: js">function draw() { + var canvas = document.getElementById('canvas'); + if (canvas.getContext){ + var ctx = canvas.getContext('2d'); + + // Quadratric curves example + ctx.beginPath(); + ctx.moveTo(75,40); + ctx.bezierCurveTo(75,37,70,25,50,25); + ctx.bezierCurveTo(20,25,20,62.5,20,62.5); + ctx.bezierCurveTo(20,80,40,102,75,120); + ctx.bezierCurveTo(110,102,130,80,130,62.5); + ctx.bezierCurveTo(130,62.5,130,25,100,25); + ctx.bezierCurveTo(85,25,75,37,75,40); + ctx.fill(); + } +} +</pre> + +<p>{{EmbedLiveSample("Cubic_Bezier_curves", 160, 160, "https://mdn.mozillademos.org/files/207/Canvas_bezier.png")}}</p> + +<h3 id="矩形">矩形</h3> + +<p>除了在{畫矩形}段落中提到的三個方法，還有rect()方法能夠在畫布上畫矩形；rect()方法會在目前路徑下加入一個矩形繪圖路徑。</p> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.bezierCurveTo", "rect(x, y, width, height)")}}</dt> + <dd>畫一個左上角位於(x, y)、寬width、高height的矩形。</dd> +</dl> + +<p>呼叫這個方法，moveTo()方法會以(0, 0)參數被自動呼叫，所以目前的下筆點跟者自動被設為預設座標。</p> + +<h3 id="多樣組合">多樣組合</h3> + +<p>截至目前為止，我們都只用一種路徑函數在各個範例裡作圖，不過，其實繪圖時並沒有任何使用數量或種類上的路徑函數限制，所以最後我們來試著組合各樣路徑繪圖函數來畫一些十分有名的遊戲角色。</p> + +<div class="hidden"> +<pre class="brush: html"><html> + <body onload="draw();"> + <canvas id="canvas" width="150" height="150"></canvas> + </body> +</html> +</pre> +</div> + +<pre class="brush: js">function draw() { + var canvas = document.getElementById('canvas'); + if (canvas.getContext){ + var ctx = canvas.getContext('2d'); + + roundedRect(ctx,12,12,150,150,15); + roundedRect(ctx,19,19,150,150,9); + roundedRect(ctx,53,53,49,33,10); + roundedRect(ctx,53,119,49,16,6); + roundedRect(ctx,135,53,49,33,10); + roundedRect(ctx,135,119,25,49,10); + + ctx.beginPath(); + ctx.arc(37,37,13,Math.PI/7,-Math.PI/7,false); + ctx.lineTo(31,37); + ctx.fill(); + + for(var i=0;i<8;i++){ + ctx.fillRect(51+i*16,35,4,4); + } + + for(i=0;i<6;i++){ + ctx.fillRect(115,51+i*16,4,4); + } + + for(i=0;i<8;i++){ + ctx.fillRect(51+i*16,99,4,4); + } + + ctx.beginPath(); + ctx.moveTo(83,116); + ctx.lineTo(83,102); + ctx.bezierCurveTo(83,94,89,88,97,88); + ctx.bezierCurveTo(105,88,111,94,111,102); + ctx.lineTo(111,116); + ctx.lineTo(106.333,111.333); + ctx.lineTo(101.666,116); + ctx.lineTo(97,111.333); + ctx.lineTo(92.333,116); + ctx.lineTo(87.666,111.333); + ctx.lineTo(83,116); + ctx.fill(); + + ctx.fillStyle = "white"; + ctx.beginPath(); + ctx.moveTo(91,96); + ctx.bezierCurveTo(88,96,87,99,87,101); + ctx.bezierCurveTo(87,103,88,106,91,106); + ctx.bezierCurveTo(94,106,95,103,95,101); + ctx.bezierCurveTo(95,99,94,96,91,96); + ctx.moveTo(103,96); + ctx.bezierCurveTo(100,96,99,99,99,101); + ctx.bezierCurveTo(99,103,100,106,103,106); + ctx.bezierCurveTo(106,106,107,103,107,101); + ctx.bezierCurveTo(107,99,106,96,103,96); + ctx.fill(); + + ctx.fillStyle = "black"; + ctx.beginPath(); + ctx.arc(101,102,2,0,Math.PI*2,true); + ctx.fill(); + + ctx.beginPath(); + ctx.arc(89,102,2,0,Math.PI*2,true); + ctx.fill(); + } +} + +// A utility function to draw a rectangle with rounded corners. + +function roundedRect(ctx,x,y,width,height,radius){ + ctx.beginPath(); + ctx.moveTo(x,y+radius); + ctx.lineTo(x,y+height-radius); + ctx.quadraticCurveTo(x,y+height,x+radius,y+height); + ctx.lineTo(x+width-radius,y+height); + ctx.quadraticCurveTo(x+width,y+height,x+width,y+height-radius); + ctx.lineTo(x+width,y+radius); + ctx.quadraticCurveTo(x+width,y,x+width-radius,y); + ctx.lineTo(x+radius,y); + ctx.quadraticCurveTo(x,y,x,y+radius); + ctx.stroke(); +} +</pre> + +<div id="section_18"> +<p>結果如下:</p> + +<p>{{EmbedLiveSample("Making_combinations", 160, 160)}}</p> + +<p>畫出這樣的圖其實沒有想像中的困難，所以我們就不再描述細節了，其中比較需要注意的是，我們在繪圖環境上用了fillStyle屬性以及一個自定義的效用函數(roundedRect())，利用效用函數來執行時常重複的繪圖工作可以幫忙減少程式碼數量與複雜度。</p> + +<p>稍後我們會更進一步介紹fillStyle屬性，這個範例我們所做是的透過fillStyle屬性來改變路徑填滿色為白色，然後再改回預設黑色，來變換填滿顏色，。</p> + +<p>{{PreviousNext("Web/Guide/HTML/Canvas_tutorial/Basic_usage", "Web/Guide/HTML/Canvas_tutorial/Using_images")}}</p> +</div> +</div> + +<h2 id="Path2D_objects">Path2D objects</h2> + +<p>如同前面的範例，canvas 上常常會畫上一連串的繪圖路徑，為了簡化程式碼還有改善效能，我們可以利用 {{domxref("Path2D")}} 物件 (目前在較先進的瀏覽器上已經有提供了)。Path2D 讓我們可以快取和記錄繪圖指令，方便快速重複地繪圖，底下我就來看看如何使用 Path2D :</p> + +<p>{{domxref("Path2D.Path2D", "Path2D()")}}</p> + +<p> Path2D 的建構子，可接受的參數有無參數、另一個 Path2D 物件、 字元表式的 <a href="/en-US/docs/Web/SVG/Tutorial/Paths">SVG path</a>:</p> + +<pre class="brush: js">new Path2D(); // 不傳入參數會回傳一個空的 Path2D 物件 +new Path2D(path); // 複製傳入的 Path2D 物件，然後以之建立 Path2D 物件 +new Path2D(d); // 以傳入的 SVG 路徑建立 Path2D 物件</pre> + +<p>所有已知的 <a href="https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D#Paths">路徑 API</a>，如 rect, arc 等等，都可以在 Path2D 上找到。</p> + +<p>Path2D 物件還可以加入其他 Path2D 物件，這讓我們可以很方便的組合多個物件使用。</p> + +<p>{{domxref("Path2D.addPath", "Path2D.addPath(path [, transform])")}}</p> + +<p> addPath 增加一個 Path2D 物件，其中的非必要參數是變形矩陣。</p> + +<h3 id="Path2D_example">Path2D example</h3> + +<p>這個例子用 Path2D 物件將矩形和圓形的繪圖路徑存起來，以供之後使用。而配合新的 Path2D API，有一些繪圖方法更接受傳入 Path2D 作為繪圖路徑使用，例如下方本例所用到的 stroke 和 fill。</p> + +<pre class="brush: js;highlight[6,9]">function draw() { + var canvas = document.getElementById('canvas'); + if (canvas.getContext){ + var ctx = canvas.getContext('2d'); + + var rectangle = new Path2D(); + rectangle.rect(10, 10, 50, 50); + + var circle = new Path2D(); + circle.moveTo(125, 35); + circle.arc(100, 35, 25, 0, 2 * Math.PI); + + ctx.stroke(rectangle); + ctx.fill(circle); + } +}</pre> + +<p>{{EmbedLiveSample("Path2D_example", 130, 110, "https://mdn.mozillademos.org/files/9851/path2d.png")}}</p> + +<h3 id="使用向量路徑_(SVG_paths)">使用向量路徑 (SVG paths)</h3> + +<p>另一個強而有力的特色是在 SVG 和 Canvas 中我們都可以使用 SVG path。</p> + +<p>下面的路徑會移到座標點 (10, 10) (M10, 10)，然後水平右移 80 點 (h 80)，垂至下移 80 點 (v 80) 水平左移 80 點 (h -80) 最後回到起始點 (z)，請到<a href="https://developer.mozilla.org/en-US/docs/Web/API/Path2D.Path2D#Using_SVG_paths"><code>Path2D</code> 建構子頁面</a>看繪圖範例結果。</p> + +<pre class="brush: js;">var p = new Path2D("M10 10 h 80 v 80 h -80 Z");</pre> + +<div>{{PreviousNext("Web/API/Canvas_API/Tutorial/Basic_usage", "Web/API/Canvas_API/Tutorial/Applying_styles_and_colors")}}</div> + +<p> </p> diff --git a/files/zh-tw/web/api/canvas_api/tutorial/drawing_text/index.html b/files/zh-tw/web/api/canvas_api/tutorial/drawing_text/index.html new file mode 100644 index 0000000000..cfafa8a5a8 --- /dev/null +++ b/files/zh-tw/web/api/canvas_api/tutorial/drawing_text/index.html @@ -0,0 +1,397 @@ +--- +title: 使用canvas繪製文字 +slug: Web/API/Canvas_API/Tutorial/Drawing_text +translation_of: Web/API/Canvas_API/Tutorial/Drawing_text +--- +<div>{{CanvasSidebar}} {{PreviousNext("Web/API/Canvas_API/Tutorial/Applying_styles_and_colors", "Web/API/Canvas_API/Tutorial/Using_images")}}</div> + +<p>{{ gecko_minversion_header("1.9") }}</p> + +<p><code><a href="/en/HTML/Canvas" title="en/HTML/Canvas">canvas</a></code>元素支援在<a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/#text-0" title="http://www.whatwg.org/specs/web-apps/current-work/#text">標準 HTML 5 特色</a>以及少許實驗性的Mozilla方法和功能上繪製文字。</p> + +<p>文字可以包括任何Unicode字元，即使用那些超出“基本多文種平面”的字元也可以。</p> + +<p>{{ fx_minversion_note("3.5", '在Firefox 3.5或之後的版本，當繪圖時，任何對於 <a class="internal" href="/en/Canvas_tutorial/Applying_styles_and_colors#Shadows" title="En/Canvas tutorial/Applying styles and colors#Shadows">shadow effects</a>（陰影效果）的處理可以使用在文字上。') }}</p> + +<h2 id="Method_overview" name="Method_overview">方法概述</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td><code>void <a class="internal" href="/en/Drawing_text_using_a_canvas#fillText()" title="en/Drawing text using a canvas#fillText()">fillText</a>(in <a class="internal" href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a> text, in float x, in float y, [optional] in float maxWidth);</code> {{ gecko_minversion_inline("1.9.1") }}</td> + </tr> + <tr> + <td><a class="internal" href="/nsIDOMTextMetrics" title="nsIDOMTextMetrics"><span style="font-family: monospace;">nsIDOMTextMetrics</span></a><code> <a class="internal" href="/en/Drawing_text_using_a_canvas#measureText()" title="en/Drawing text using a canvas#measureText()">measureText</a>(in DOMString textToMeasure);</code> {{ gecko_minversion_inline("1.9.1") }}</td> + </tr> + <tr> + <td><code>void <a href="#mozDrawText.28.29">mozDrawText</a>(in DOMString textToDraw); {{ deprecated_inline() }}</code></td> + </tr> + <tr> + <td><code>float <a href="#mozMeasureText.28.29">mozMeasureText</a>(in DOMString textToMeasure);</code><code> {{ deprecated_inline() }}</code></td> + </tr> + <tr> + <td><code>void <a href="#mozPathText.28.29">mozPathText</a>(in DOMString textToPath);</code></td> + </tr> + <tr> + <td><code>void <a href="#mozTextAlongPath.28.29">mozTextAlongPath</a>(in DOMString textToDraw, in boolean stroke);</code></td> + </tr> + <tr> + <td><code>void <a class="internal" href="/en/Drawing_text_using_a_canvas#strokeText()" title="en/Drawing text using a canvas#strokeText()">strokeText</a>(in DOMString text, in float x, in float y, [optional] in float maxWidth);</code> {{ gecko_minversion_inline("1.9.1") }}</td> + </tr> + </tbody> +</table> + +<p> </p> + +<h2 id="Attributes" name="Attributes">屬性</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td class="header">屬性</td> + <td class="header">型別</td> + <td class="header">描述</td> + </tr> + <tr> + <td><code>font</code> {{ gecko_minversion_inline("1.9.1") }}</td> + <td><code><a href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a></code></td> + <td> + <p>當前的文字樣式被用在繪製文字。該字串使用和 <a href="/en/CSS/font" title="en/CSS/font">CSS font</a>（樣式表字型）相同的語法。要改變繪製文字的樣式，只要簡單的改變它的屬性值即可，就像下面展示的，預設的字型是10px（像素） sans-serif（字型名稱）</p> + + <p>例如:</p> + + <pre class="eval"> +ctx.font = "20pt Arial";</pre> + </td> + </tr> + <tr> + <td><code>mozTextStyle</code> {{ deprecated_inline() }}</td> + <td><code><a href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a></code></td> + <td> + <p>由上面的Html5<code>字型</code> 屬性取代</p> + </td> + </tr> + <tr> + <td><code>textAlign</code> {{ gecko_minversion_inline("1.9.1") }}</td> + <td><code><a href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a></code></td> + <td> + <p>當前繪製文字所使用的文字對齊方式。 可使用的值：</p> + + <dl> + <dt>left</dt> + <dd>文字靠左對齊。</dd> + <dt>right</dt> + <dd>文字靠右對齊。</dd> + <dt>center</dt> + <dd>文字置中對齊。</dd> + <dt>start</dt> + <dd>文字依照行首對齊 (書寫習慣由左到右的地區就靠左對齊，書寫習慣由右到左的就靠右對齊。).</dd> + <dt>end</dt> + <dd>文字依照行尾對齊（書寫習慣由左到右的地區就靠右對齊，書寫習責由右到左的地區就靠左對齊。）</dd> + </dl> + + <p>預設的值是 <code>start</code>.</p> + </td> + </tr> + <tr> + <td><code>textBaseline</code> {{ gecko_minversion_inline("1.9.1") }}</td> + <td><code><a href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a></code></td> + <td> + <p>當前繪製文字的基線位置 可使用的值：</p> + + <dl> + <dt>top</dt> + <dd>基線在字元區塊的頂部（圖中top of the squre位置）。</dd> + <dt>hanging（懸掛）</dt> + <dd>文字基線在拼音文字頂部的位置（圖中hanging baseline） <em>當前仍未支援；會顯示 <strong>alphabetic</strong>代替。</em></dd> + <dt>middle</dt> + <dd>文字基線在字元區塊的中間。</dd> + <dt>alphabetic（拼音文字）</dt> + <dd>這是一般拼音文字底線的位置。</dd> + <dt>ideographic（表意文字）</dt> + <dd>文字在表意文字（如漢字）底部的位置 <em>當前仍未支援；會顯示<strong>alphabetic</strong>代替。</em></dd> + <dt>bottom</dt> + <dd>基線在拼音文字下伸部的位置 這與ideographic的基線位置不同，因為表意文字沒有下伸部</dd> + </dl> + + <p>預設使用 <code>alphabetic</code>.</p> + </td> + </tr> + </tbody> +</table> + +<p>下圖展示了textBaseline屬性所支援的各種基線，感謝 <a class="external" href="http://www.whatwg.org/" title="http://www.whatwg.org/">WHATWG</a>.</p> + +<p><img alt="top of em squre（字元區塊頂部）大致在字型中所有字母的最頂部位置，hanging basline（懸掛基線）則是在一些特殊（較小的,像是“आ”）字母頂部，middle則是在top of em squre（字元區塊頂部和bottom of em squre（字元區塊底部）的中間，alphabetic（拼音文字）的基線位置則是在一般拼音字母如Á，ÿ，f，Ω的底線位置。ideographic（表意文字）的基線在字元的底部位置，bottom of em squre（字元區塊底部）則大致是字型中所有字母的最底部位置。而top and bottom of the bounding box（上下的區域範圍線）則比這些基線都來得更遠，基於字母的高度可能超過字元區塊頂部和底部的範圍。" src="http://www.whatwg.org/specs/web-apps/current-work/images/baselines.png"></p> + +<h2 id="Methods" name="Methods">方法</h2> + +<h3 id="fillText()">fillText()</h3> + +<p>繪製文字使用<code>font</code>屬性指定的文字樣式，對齊則使用<code>textAlign</code>屬性，而指定基線則使用<code>textBaseline</code>. 填充文字當前使用<code>fillStyle</code>，而<code>strokeStyle</code>則被忽略</p> + +<div class="note"><strong>注意：</strong>這個方法在 Gecko 1.9.1 (Firefox 3.5)時引進，且是HTML 5標準的一部分.</div> + +<pre>void fillText( + in DOMString textToDraw, + in float x, + in float y, + [optional] in float maxWidth +); +</pre> + +<h5 id="參數">參數</h5> + +<dl> + <dt><code>textToDraw</code></dt> + <dd>將文字繪製到文本中。</dd> + <dt><code>x</code></dt> + <dd>繪製位置的x座標。</dd> + <dt><code>y</code></dt> + <dd>繪製位置的y座標。</dd> + <dt><code>maxWidth</code></dt> + <dd>最大寬度，可選用的；繪製字串最大長度 如果指定此參數，當字串被計算出比這個值更寬，它會自動選擇水平方向更窄的字型（如果有可用的字型或是有可讀的字型可以嵌入當前字型之中），或者縮小字型。</dd> +</dl> + +<h5 id="範例">範例</h5> + +<pre class="brush: js">ctx.fillText("Sample String", 10, 50); +</pre> + +<h3 id="mozMeasureText.28.29" name="mozMeasureText.28.29">measureText()</h3> + +<p>測量文字。返回一個物件包含了寬度，像素值，所指定的文字會以當前的文字樣式繪製。</p> + +<div class="note"><strong>注意：</strong> 這個方法在 Gecko 1.9.1 (Firefox 3.5) 引進，且是HTML 5標準的一部分。</div> + +<pre class="eval">nsIDOMTextMetrics measureText( + in DOMString textToMeasure +); +</pre> + +<h6 id="Parameters_2" name="Parameters_2">參數</h6> + +<dl> + <dt><code>textToMeasure</code></dt> + <dd>該字串的像素值。</dd> +</dl> + +<h6 id="Return_value" name="Return_value">返回值</h6> + +<p><a class="internal" href="/nsIDOMTextMetrics" title="nsIDOMTextMetrics"><code>nsIDOMTextMetrics</code></a>物件的<code>width</code>屬性在繪製時會將數字設定給CSS 的像素值寬度。</p> + +<h3 id="mozDrawText.28.29" name="mozDrawText.28.29">mozDrawText()</h3> + +<p>{{ deprecated_header() }}</p> + +<p>繪製文字使用由<code>mozTextStyle</code>屬性的文字樣式。文本當前的填充顏色被用來當做文字顏色。</p> + +<div class="note"><strong>注意：</strong>這個方法已經不被建議使用,請使用正式的HTML 5方法 <code>fillText()</code> and <code>strokeText()</code>.</div> + +<pre class="eval">void mozDrawText( + in DOMString textToDraw +); +</pre> + +<h6 id="Parameters" name="Parameters">參數</h6> + +<dl> + <dt><code>textToDraw</code></dt> + <dd>將文字繪製到文本。</dd> +</dl> + +<h6 id="Example" name="Example">範例</h6> + +<pre class="brush: js">ctx.translate(10, 50); +ctx.fillStyle = "Red"; +ctx.mozDrawText("Sample String"); +</pre> + +<p>這個範例將文字“Sample String”繪製到畫布（canvas）上。</p> + +<h3 id="mozMeasureText.28.29" name="mozMeasureText.28.29">mozMeasureText()</h3> + +<p>{{ deprecated_header() }}</p> + +<p>返回寬度，像素值，指定文字</p> + +<div class="note"><strong>注意：</strong>這個方法已經已宣告棄用，請使用正式的HTML 5方法<code>measureText()</code>.</div> + +<pre class="eval">float mozMeasureText( + in DOMString textToMeasure +); +</pre> + +<h6 id="Parameters_2" name="Parameters_2">參數</h6> + +<dl> + <dt><code>textToMeasure</code></dt> + <dd>字串的寬度像素值</dd> +</dl> + +<h6 id="Return_value" name="Return_value">返回值</h6> + +<p>文字的寬度像素值</p> + +<h6 id="Example_2" name="Example_2">範例</h6> + +<pre class="brush: js">var text = "Sample String"; +var width = ctx.canvas.width; +var len = ctx.mozMeasureText(text); +ctx.translate((width - len)/2, 0); +ctx.mozDrawText(text); +</pre> + +<p>這個範例測量了字串的寬度，接著使用這個資訊將它畫在畫布（canvas）的水平中心。</p> + +<h3 id="mozPathText.28.29" name="mozPathText.28.29">mozPathText()</h3> + +<p>給文字路徑加上外框線，如果你想要的話，它允許你替文字加上框線代替填充它。</p> + +<pre class="eval">void mozPathText( + in DOMString textToPath +); +</pre> + +<h6 id="Parameters_3" name="Parameters_3">參數</h6> + +<dl> + <dt><code>textToPath</code></dt> + <dd>為當前的文字路徑加上框線</dd> +</dl> + +<h6 id="Example_3" name="Example_3">Example</h6> + +<pre class="brush: js">ctx.fillStyle = "green"; +ctx.strokeStyle = "black"; +ctx.mozPathText("Sample String"); +ctx.fill() +ctx.stroke() +</pre> + +<p>這個範例繪出文字“Sample String”，填充顏色是綠色，外框顏色是黑色。</p> + +<h3 id="mozTextAlongPath.28.29" name="mozTextAlongPath.28.29">mozTextAlongPath()</h3> + +<p>Adds (or draws) the specified text along the current path.</p> + +<pre class="eval">void mozTextAlongPath( + in DOMString textToDraw, + in boolean stroke +); +</pre> + +<h6 id="Parameters_4" name="Parameters_4">參數</h6> + +<dl> + <dt><code>textToDraw</code></dt> + <dd>沿著指定路徑繪出文字</dd> + <dt><code>stroke</code></dt> + <dd>如果參數是 <code>true</code>（真值），文字會沿著指定路徑繪製。如果 <code>false</code>（假值），這個文字則會加入到路徑之中，再沿著當前路徑繪製。</dd> +</dl> + +<h6 id="Remarks" name="Remarks">備註</h6> + +<p>字體不會沿著路徑曲線縮放或變形，反而在彎曲路徑下，字體每次計算都會當成是直線在處理。這可以用來建立一些特殊的效果。</p> + +<h3 id="strokeText()">strokeText()</h3> + +<p>繪製文字使用<code>font</code>屬性指定的文字樣式，對齊則使用<code>textAlign</code>屬性，而指定基線則使用<code>textBaseline</code>. 當前使用<code>strokeStyle</code>來建立文字外框。</p> + +<div class="note"><strong>注意：</strong> 這個方法在 Gecko 1.9.1 (Firefox 3.5)時引進，且是HTML 5標準的一部分。</div> + +<pre>void strokeText( + in DOMString textToDraw, + in float x, + in float y, + [optional] in float maxWidth +); +</pre> + +<h5 id="參數_2">參數</h5> + +<dl> + <dt><code>textToDraw</code></dt> + <dd>將文字繪製到文本中。</dd> + <dt><code>x</code></dt> + <dd>繪製位置的x座標。</dd> + <dt><code>y</code></dt> + <dd>繪製位置的y座標</dd> + <dt><code>maxWidth</code></dt> + <dd>最大寬度，可選用的；繪製字串最大長度 如果指定此參數，當字串被計算出比這個值更寬，它會自動選擇水平方向更窄的字型（如果有可用的字型或是有可讀的字型可以嵌入當前字型之中），或者縮小字型。</dd> +</dl> + +<h5 id="範例_2">範例</h5> + +<pre class="brush: js">ctx.strokeText("Sample String", 10, 50); +</pre> + +<h2 id="Remarks_2" name="Remarks_2">備註</h2> + +<ul> + <li>請見 <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/#text" title="http://www.whatwg.org/specs/web-apps/current-work/#text">WHATWG specification</a> 關於HTML 5 canvas text的說明。</li> + <li>你不需要特別的文本來使用這些功能；2D的文本就可以執行得很好。</li> + <li>所有的繪圖都使用即時變化來完成。</li> +</ul> + +<h2 id="Additional_examples" name="Additional_examples">其它範例</h2> + +<ul> + <li><a class="link-https" href="https://bugzilla.mozilla.org/attachment.cgi?id=273497">繞著路徑繪製外框文字</a></li> + <li><a class="link-https" href="https://bugzilla.mozilla.org/attachment.cgi?id=273498">沿著路徑繪製</a></li> + <li><a class="link-https" href="https://bugzilla.mozilla.org/attachment.cgi?id=273499">動畫文字繞圓移動</a>.</li> +</ul> + +<h1 id="瀏覽器兼容性">瀏覽器兼容性</h1> + +<p>{{ CompatibilityTable() }}</p> + +<div id="compat-desktop"> +<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>1+</td> + <td>3.5+</td> + <td>9.0</td> + <td>10.5</td> + <td>4.0</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>2.1</td> + <td>{{ CompatUnknown() }}</td> + <td>9.0</td> + <td>11.0</td> + <td>3.2</td> + </tr> + </tbody> +</table> +</div> +</div> + +<p> </p> diff --git a/files/zh-tw/web/api/canvas_api/tutorial/index.html b/files/zh-tw/web/api/canvas_api/tutorial/index.html new file mode 100644 index 0000000000..15280a881d --- /dev/null +++ b/files/zh-tw/web/api/canvas_api/tutorial/index.html @@ -0,0 +1,69 @@ +--- +title: Canvas 教學文件 +slug: Web/API/Canvas_API/Tutorial +translation_of: Web/API/Canvas_API/Tutorial +--- +<div>{{CanvasSidebar}}</div> + +<p><a href="/en-US/docs/HTML/Canvas" title="HTML/Canvas"><img alt="" src="https://mdn.mozillademos.org/files/257/Canvas_tut_examples.jpg" style="float: right; height: 450px; width: 200px;"></a></p> + +<div class="summary"> +<p><a href="/en-US/docs/HTML/Canvas" title="HTML/Canvas"><strong><code><canvas></code></strong></a> 是一個 <a href="/en-US/docs/HTML" title="HTML">HTML</a> 元素，我們可以利用程式腳本在這個元素上繪圖（通常是用 <a href="/en-US/docs/JavaScript" title="JavaScript">JavaScript</a>）。除了繪圖，我們還可以合成圖片或做一些簡單（或是<a href="/en-US/docs/HTML/Canvas/A_Basic_RayCaster" title="A_Basic_RayCaster">不那麼簡單</a>）的動畫。右方的影像便是一些運用 <canvas> 的例子，接下來我們將會在教學文件中一一說明<span style="line-height: inherit;">。</span></p> +</div> + +<p><span class="seoSummary">本教學從基礎知識開始，描述如何利用 <canvas> 進行 2D 繪圖。教學中的範例會讓各位清楚瞭解 <canvas> 該如何運用，另外也會提供程式碼範例，讓大家嘗試製作自己的內容。</span></p> + +<p><code><canvas></code> 最早是由 Apple 為 Mac OS X Dashboard 所提出，之後 Safari 和 Google Chrome 也都採用。<a href="/en-US/docs/Gecko" title="Gecko">Gecko</a> 1.8 作基礎的瀏覽器，如 Firefox 1.5 也都提供了支援。<code><canvas></code> 元素是 <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/">WhatWG Web applications 1.0</a>（也就是 HTML5）規範的一部分，目前所有主流的瀏覽器都已支援。</p> + +<h2 id="Before_you_start" name="Before_you_start">在開始之前</h2> + +<p><code><canvas></code> 並不困難，但你需要了解基本的 <a href="/en-US/docs/HTML" title="HTML">HTML</a> 與 <a href="/en-US/docs/JavaScript" title="JavaScript">JavaScript</a>。部分舊版瀏覽器不支援<code> <canvas>，不過基本上現今所有主流的瀏覽器都有支援。</code>預設的畫布大小是 300px * 150px（寬 * 高）。但你也可以透過 HTML 寬、高屬性（{{Glossary("attribute")}}）自訂。為了在畫布上作畫，我們使用了一個 JavaScript context 物件來即時繪製圖形。</p> + +<h2 id="In_this_tutorial" name="In_this_tutorial">教學文件</h2> + +<ul> + <li><a href="/zh-TW/docs/Web/Guide/HTML/Canvas_tutorial/Basic_usage" title="Canvas_tutorial/Basic_usage">基本用途</a></li> + <li><a href="/zh-TW/docs/Web/Guide/HTML/Canvas_tutorial/Drawing_shapes" title="Canvas_tutorial/Drawing_shapes">繪製圖形</a></li> + <li><a href="/zh-TW/docs/Web/Guide/HTML/Canvas_tutorial/Applying_styles_and_colors" title="Canvas_tutorial/Applying_styles_and_colors">套用樣式與顏色</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Drawing_text">繪製文字</a></li> + <li><a href="/zh-TW/docs/Web/Guide/HTML/Canvas_tutorial/Using_images" title="Canvas_tutorial/Using_images">使用影像</a></li> + <li><a href="/zh-TW/docs/Web/Guide/HTML/Canvas_tutorial/Transformations" title="Canvas_tutorial/Transformations">變形效果</a></li> + <li><a href="/zh-TW/docs/Web/Guide/HTML/Canvas_tutorial/Compositing" title="Canvas_tutorial/Compositing">合成效果</a></li> + <li><a href="/zh-TW/docs/Web/Guide/HTML/Canvas_tutorial/Basic_animations" title="Canvas_tutorial/Basic_animations">基礎動畫</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Advanced_animations">進階動畫</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Pixel_manipulation_with_canvas">像素控制</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Hit_regions_and_accessibility">Hit regions and accessibility</a></li> + <li><a href="/zh-TW/docs/Web/Guide/HTML/Canvas_tutorial/Optimizing_canvas" title="Canvas_tutorial/Optimizing_canvas">最佳化 canvas</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Finale">Finale</a></li> +</ul> + +<h2 id="See_also" name="See_also">參見</h2> + +<ul> + <li><a href="/en-US/docs/HTML/Canvas" title="HTML/Canvas">Canvas topic page</a></li> + <li><a class="external external-icon" href="http://visitmix.com/labs/ai2canvas/" title="http://visitmix.com/labs/ai2canvas/">Adobe Illustrator to Canvas plug-in</a></li> + <li><a class="external external-icon" href="http://www.html5canvastutorials.com/" title="http://www.html5canvastutorials.com/">HTML5CanvasTutorials</a></li> + <li><a class="external external-icon" href="http://creativejs.com/2011/08/31-days-of-canvas-tutorials/" title="http://creativejs.com/2011/08/31-days-of-canvas-tutorials/">31 days of canvas tutorials</a></li> + <li><a href="/en-US/docs/HTML/Canvas/Drawing_Graphics_with_Canvas" title="Drawing_Graphics_with_Canvas">Drawing Graphics with Canvas</a></li> + <li><a href="/en-US/docs/tag/Canvas_examples" title="tag/Canvas_examples">Canvas examples</a></li> + <li><a class="external" href="http://html5tutorial.com" title="http://html5tutorial.com">HTML5 Tutorial</a></li> + <li><a href="/en-US/docs/Drawing_text_using_a_canvas" title="Drawing_text_using_a_canvas">Drawing Text Using a Canvas</a></li> + <li><a class="external" href="http://developer.apple.com/library/safari/#documentation/AudioVideo/Conceptual/HTML-canvas-guide/AddingText/AddingText.html#//apple_ref/doc/uid/TP40010542-CH6-SW4" title="Adding Text to Canvas">Adding Text to Canvas</a></li> + <li><a class="external" href="http://www.canvasdemos.com/" title="Canvas Demos">Canvas Demos - Games, applications, tools and tutorials</a></li> + <li><a class="external" href="http://canvimation.github.com/" title="http://canvimation.github.com/">Canvas Drawing and Animation Application</a></li> + <li><a class="external" href="http://billmill.org/static/canvastutorial/" title="http://billmill.org/static/canvastutorial/">interactive canvas tutorial</a></li> + <li><a class="external" href="http://blog.nihilogic.dk/2009/02/html5-canvas-cheat-sheet.html" title="http://blog.nihilogic.dk/2009/02/html5-canvas-cheat-sheet.html">Canvas Cheat Sheet with all attributes and methods</a></li> + <li><a class="external" href="http://visitmix.com/labs/ai2canvas/" title="http://visitmix.com/labs/ai2canvas/">Adobe Illustrator to Canvas plug-in</a></li> + <li><a class="external" href="http://www.html5canvastutorials.com/" title="http://www.html5canvastutorials.com/">HTML5CanvasTutorials</a></li> + <li><a class="external" href="http://html5tutorial.com/how-to-draw-n-grade-bezier-curve-with-canvas-api" title="http://html5tutorial.com/how-to-draw-n-grade-bezier-curve-with-canvas-api">How to draw N grade Bézier curves with the Canvas API</a></li> + <li><a class="external" href="http://creativejs.com/2011/08/31-days-of-canvas-tutorials/" title="http://creativejs.com/2011/08/31-days-of-canvas-tutorials/">31 days of canvas tutorials</a></li> + <li><a href="http://www.w3.org/TR/2dcontext/" title="http://www.w3.org/TR/2dcontext/">W3C Standard</a></li> +</ul> + +<h2 id="致歉各位貢獻者">致歉各位貢獻者</h2> + +<p>由於 2013/6/17 那一週的不幸技術錯誤，所有有關本教學的歷史紀錄，包括過去所有貢獻者的紀錄都遺失了，我們深感抱歉，希望各位可以原諒這一次不幸的意外。</p> + +<div>{{ Next("Web/Guide/HTML/Canvas_tutorial/Basic_usage") }}</div> + +<div> </div> diff --git a/files/zh-tw/web/api/canvas_api/tutorial/optimizing_canvas/index.html b/files/zh-tw/web/api/canvas_api/tutorial/optimizing_canvas/index.html new file mode 100644 index 0000000000..7fb8b35666 --- /dev/null +++ b/files/zh-tw/web/api/canvas_api/tutorial/optimizing_canvas/index.html @@ -0,0 +1,26 @@ +--- +title: 最佳化canvas +slug: Web/API/Canvas_API/Tutorial/Optimizing_canvas +translation_of: Web/API/Canvas_API/Tutorial/Optimizing_canvas +--- +<p>{{HTMLElement("canvas")}}在網頁2D繪圖上被大量運用於遊戲和複雜視覺化效果上。隨著繪圖複雜度越來越高，效能問題也會逐一浮現，所以最後我們在這邊列出一些最佳化畫布的方法，避免一些效能問題:</p> +<ul> + <li> + 在畫面之外的畫布上先行渲染相似或重複的物件 + </li> + <li>批次性執行繪圖，例如一次畫數個線條而非分開一次一次畫</li> + <li> + 使用整數位座標值，盡量避免小數點值 + </li> + <li>避免不必要的畫布狀態改變</li> + <li> + 只渲染不同處，不要全部重新渲染 + </li> + <li>對於複雜需求可以利用多個畫布分層構成</li> + <li> + 盡量不要用shadowBlur屬性 + </li> + <li>使用{{domxref("window.requestAnimationFrame()")}}</li> + <li>用<a href="http://jsperf.com" title="http://jsperf.com">JSPerf</a>測試效能</li> +</ul> +<p>{{PreviousNext("Web/Guide/HTML/Canvas_tutorial/Basic_animations")}}</p> diff --git a/files/zh-tw/web/api/canvas_api/tutorial/pixel_manipulation_with_canvas/index.html b/files/zh-tw/web/api/canvas_api/tutorial/pixel_manipulation_with_canvas/index.html new file mode 100644 index 0000000000..398ef70484 --- /dev/null +++ b/files/zh-tw/web/api/canvas_api/tutorial/pixel_manipulation_with_canvas/index.html @@ -0,0 +1,265 @@ +--- +title: Pixel manipulation with canvas +slug: Web/API/Canvas_API/Tutorial/Pixel_manipulation_with_canvas +translation_of: Web/API/Canvas_API/Tutorial/Pixel_manipulation_with_canvas +--- +<div>{{CanvasSidebar}} {{PreviousNext("Web/API/Canvas_API/Tutorial/Advanced_animations", "Web/API/Canvas_API/Tutorial/Hit_regions_and_accessibility")}}</div> + +<div class="summary"> +<p>直到目前為止，我們還沒真正了解 pixels 在 canvas上的運用。使用<code>ImageData</code>物件，可直接對pixel 裡的陣列資料<strong>讀(read)</strong>和<strong>寫(write)</strong>。在接下的內容中，也可了解到如何使影像平滑化(反鋸齒)及如何將影像保存在canvas之中。</p> +</div> + +<h2 id="ImageData物件"><code>ImageData</code>物件</h2> + +<p>{{domxref("ImageData")}} 物件代表canvas區中最基礎的像素。</p> + +<p>包含它只可讀的屬性:</p> + +<dl> + <dt><code>width</code></dt> + <dd>影像中的寬度，以pixels為單位</dd> + <dt><code>height</code></dt> + <dd>影像中的高度，以pixels為單位</dd> + <dt><code>data</code></dt> + <dd>{{jsxref("Uint8ClampedArray")}} 代表一維陣列包含RGBA 格式。整數值介於0到255之間(包含255)。</dd> +</dl> + +<p><code>data</code> 屬性返回一個{{jsxref("Uint8ClampedArray")}}，它可被當作為pixel的初始資料。每個pixel用4個1byte值做代表分別為<strong>紅</strong>，<strong>綠</strong>，<strong>藍</strong>，<strong>透明值</strong>(也就是<strong>RGBA</strong>格式)。每個顏色組成皆是介於整數值介於0到255之間。而每個組成在一個陣列中被分配為一個連續的索引。從左上角 pixel 的紅色組成中的陣列由<strong>索引 0</strong> 為始。Pixels 執行順序為從左到右,再由上到下,直到整個陣列。</p> + +<p>{{jsxref("Uint8ClampedArray")}} 包含<code>height</code> × <code>width</code>× 4 bytes的資料,同索引值從0到 (<code>height</code>×<code>width</code>×4)-1</p> + +<p>例如,讀取影像的藍色組成的值。從pixel 的第200欄、第50行，你可以照著下面的步驟:</p> + +<pre class="brush: js">blueComponent = imageData.data[((50 * (imageData.width * 4)) + (200 * 4)) + 2];</pre> + +<p>使用<code>Uint8ClampedArray.length</code>屬性來讀取影像pixel的陣列大小</p> + +<pre class="brush: js">var numBytes = imageData.data.length; +</pre> + +<h2 id="創造一個_ImageData物件">創造一個 <code>ImageData</code>物件</h2> + +<p>可以使用{{domxref("CanvasRenderingContext2D.createImageData", "createImageData()")}}方法創造一個全新空白的<code>ImageData</code> 物件。</p> + +<p>這裡有兩種<code>createImageData()</code>的方法:</p> + +<pre class="brush: js">var myImageData = ctx.createImageData(width, height);</pre> + +<p>這個方法是有規定大小尺寸.所有pixels預設是透明的黑色。</p> + +<p>下面的方法一樣是由<code>anotherImageData</code>參考尺寸大小，由<code>ImageData</code> 物件創造一個與新的一樣的大小。這些新的物件的pixel皆預設為透明的黑色。</p> + +<pre class="brush: js">var myImageData = ctx.createImageData(anotherImageData);</pre> + +<h2 id="得到pixel資料的內容">得到pixel資料的內容</h2> + +<p>可以使用<code>getImageData()</code>這個方法，去取得canvas內容中<code>ImageData</code> 物件的資料含pixel 數據(data) </p> + +<pre class="brush: js">var myImageData = ctx.getImageData(left, top, width, height);</pre> + +<p>這個方法會返回<code>ImageData</code>物件，它代表著在這canvas區域之中pixel 的數據(data) 。從各角落的點代表著 (<code>left</code>,<code>top</code>), (<code>left+width</code>, <code>top</code>), (<code>left</code>, <code>top+height</code>), and (<code>left+width</code>, <code>top+height</code>)。這些作標被設定為canvas 的空間座標單位。</p> + +<div class="note"> +<p><strong>注釋</strong>: 在<code>ImageData</code> 物件中，任何超出canvas外的pixels皆會返回透明的黑色的形式。</p> +</div> + +<p>這個方法也被展示在<a href="/en-US/docs/Web/API/Canvas_API/Manipulating_video_using_canvas">使用canvas操作影像</a>之中。</p> + +<h3 id="調色盤">調色盤</h3> + +<p>這個範例使用<a href="/en-US/docs/Web/API/CanvasRenderingContext2D/getImageData">getImageData() </a>方法去顯示在鼠標下的顏色。</p> + +<p>首先，需要一個正確的滑鼠點<code>layerX</code><em></em>和 <code>layerY</code>。在從<a href="/en-US/docs/Web/API/CanvasRenderingContext2D/getImageData">getImageData()</a> 提供pixel 陣列中(array)該點的pixel 數據(data) 。最後，使用陣列數據(array data)在<code><div></code>中設置背景色和文字去顯示該色。</p> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" width="300" height="227" style="float:left"></canvas> +<div id="color" style="width:200px;height:50px;float:left"></div> +</pre> +</div> + +<pre class="brush: js;">var img = new Image(); +img.src = 'https://mdn.mozillademos.org/files/5397/rhino.jpg'; +var canvas = document.getElementById('canvas'); +var ctx = canvas.getContext('2d'); +img.onload = function() { + ctx.drawImage(img, 0, 0); + img.style.display = 'none'; +}; +var color = document.getElementById('color'); +function pick(event) { + var x = event.layerX; + var y = event.layerY; + var pixel = ctx.getImageData(x, y, 1, 1); + var data = pixel.data; + var rgba = 'rgba(' + data[0] + ', ' + data[1] + + ', ' + data[2] + ', ' + (data[3] / 255) + ')'; + color.style.background = rgba; + color.textContent = rgba; +} +canvas.addEventListener('mousemove', pick); +</pre> + +<p>{{ EmbedLiveSample('A_color_picker', 610, 240) }}</p> + +<h2 id="在內容中寫入pixel_資料">在內容中寫入pixel 資料</h2> + +<p>可以使用<a href="/en-US/docs/Web/API/CanvasRenderingContext2D/putImageData">putImageData() </a>方法將自訂pixel 數據(data) 放入內容中:</p> + +<pre class="brush: js">ctx.putImageData(myImageData, dx, dy); +</pre> + +<p><code>dx</code> 和 <code>dy</code>參數表示填入你所希望的座標，將它代入內容中左上角的pixel 數據(data)。</p> + +<p>For example, to paint the entire image represented by <code>myImageData</code> to the top left corner of the context, you can simply do the following:</p> + +<pre class="brush: js">ctx.putImageData(myImageData, 0, 0); +</pre> + +<h3 id="灰階和負片效果">灰階和負片效果</h3> + +<p>In this example we iterate over all pixels to change their values, then we put the modified pixel array back to the canvas using <a href="/en-US/docs/Web/API/CanvasRenderingContext2D/putImageData">putImageData()</a>. The invert function simply subtracts each color from the max value 255. The grayscale function simply uses the average of red, green and blue. You can also use a weighted average, given by the formula <code>x = 0.299r + 0.587g + 0.114b</code>, for example. See <a href="http://en.wikipedia.org/wiki/Grayscale">Grayscale</a> on Wikipedia for more information.</p> + +<div class="hidden"> +<pre class="brush: html;"><canvas id="canvas" width="300" height="227"></canvas> +<div> + <input id="grayscalebtn" value="Grayscale" type="button"> + <input id="invertbtn" value="Invert" type="button"> +</div> +</pre> +</div> + +<pre class="brush: js">var img = new Image(); +img.src = 'https://mdn.mozillademos.org/files/5397/rhino.jpg'; +img.onload = function() { + draw(this); +}; + +function draw(img) { + var canvas = document.getElementById('canvas'); + var ctx = canvas.getContext('2d'); + ctx.drawImage(img, 0, 0); + img.style.display = 'none'; + var imageData = ctx.getImageData(0, 0, canvas.width, canvas.height); + var data = imageData.data; + + var invert = function() { + for (var i = 0; i < data.length; i += 4) { + data[i] = 255 - data[i]; // red + data[i + 1] = 255 - data[i + 1]; // green + data[i + 2] = 255 - data[i + 2]; // blue + } + ctx.putImageData(imageData, 0, 0); + }; + + var grayscale = function() { + for (var i = 0; i < data.length; i += 4) { + var avg = (data[i] + data[i + 1] + data[i + 2]) / 3; + data[i] = avg; // red + data[i + 1] = avg; // green + data[i + 2] = avg; // blue + } + ctx.putImageData(imageData, 0, 0); + }; + + var invertbtn = document.getElementById('invertbtn'); + invertbtn.addEventListener('click', invert); + var grayscalebtn = document.getElementById('grayscalebtn'); + grayscalebtn.addEventListener('click', grayscale); +} +</pre> + +<p>{{ EmbedLiveSample('Grayscaling_and_inverting_colors', 330, 270) }}</p> + +<h2 id="放大和平滑化(反鋸齒)">放大和平滑化(反鋸齒)</h2> + +<p>With the help of the {{domxref("CanvasRenderingContext2D.drawImage", "drawImage()")}} method, a second canvas and the {{domxref("CanvasRenderingContext2D.imageSmoothingEnabled", "imageSmoothingEnabled")}} property, we are able to zoom into our picture and see the details.</p> + +<p>We get the position of the mouse and crop an image of 5 pixels left and above to 5 pixels right and below. Then we copy that one over to another canvas and resize the image to the size we want it to. In the zoom canvas we resize a 10×10 pixel crop of the original canvas to 200×200.</p> + +<pre class="brush: js">zoomctx.drawImage(canvas, + Math.abs(x - 5), Math.abs(y - 5), + 10, 10, 0, 0, 200, 200);</pre> + +<p>Because anti-aliasing is enabled by default, we might want to disable the smoothing to see clear pixels. You can toggle the checkbox to see the effect of the <code>imageSmoothingEnabled</code> property (which needs prefixes for different browsers).</p> + +<h6 class="hidden" id="Zoom_example">Zoom example</h6> + +<div class="hidden"> +<pre class="brush: html;"><canvas id="canvas" width="300" height="227"></canvas> +<canvas id="zoom" width="300" height="227"></canvas> +<div> +<label for="smoothbtn"> + <input type="checkbox" name="smoothbtn" checked="checked" id="smoothbtn"> + Enable image smoothing +</label> +</div> +</pre> +</div> + +<pre class="brush: js">var img = new Image(); +img.src = 'https://mdn.mozillademos.org/files/5397/rhino.jpg'; +img.onload = function() { + draw(this); +}; + +function draw(img) { + var canvas = document.getElementById('canvas'); + var ctx = canvas.getContext('2d'); + ctx.drawImage(img, 0, 0); + img.style.display = 'none'; + var zoomctx = document.getElementById('zoom').getContext('2d'); + + var smoothbtn = document.getElementById('smoothbtn'); + var toggleSmoothing = function(event) { + zoomctx.imageSmoothingEnabled = this.checked; + zoomctx.mozImageSmoothingEnabled = this.checked; + zoomctx.webkitImageSmoothingEnabled = this.checked; + zoomctx.msImageSmoothingEnabled = this.checked; + }; + smoothbtn.addEventListener('change', toggleSmoothing); + + var zoom = function(event) { + var x = event.layerX; + var y = event.layerY; + zoomctx.drawImage(canvas, + Math.abs(x - 5), + Math.abs(y - 5), + 10, 10, + 0, 0, + 200, 200); + }; + + canvas.addEventListener('mousemove', zoom); +}</pre> + +<p>{{ EmbedLiveSample('Zoom_example', 620, 490) }}</p> + +<h2 id="儲存圖片">儲存圖片</h2> + +<p>The {{domxref("HTMLCanvasElement")}} provides a <code>toDataURL()</code> method, which is useful when saving images. It returns a <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/data_URIs">data URI</a> containing a representation of the image in the format specified by the <code>type</code> parameter (defaults to <a class="external external-icon" href="https://en.wikipedia.org/wiki/Portable_Network_Graphics">PNG</a>). The returned image is in a resolution of 96 dpi.</p> + +<dl> + <dt>{{domxref("HTMLCanvasElement.toDataURL", "canvas.toDataURL('image/png')")}}</dt> + <dd>Default setting. Creates a PNG image.</dd> + <dt>{{domxref("HTMLCanvasElement.toDataURL", "canvas.toDataURL('image/jpeg', quality)")}}</dt> + <dd>Creates a JPG image. Optionally, you can provide a quality in the range from 0 to 1, with one being the best quality and with 0 almost not recognizable but small in file size.</dd> +</dl> + +<p>Once you have generated a data URI from you canvas, you are able to use it as the source of any {{HTMLElement("image")}} or put it into a hyper link with a <a href="/en-US/docs/Web/HTML/Element/a#attr-download">download attribute</a> to save it to disc, for example.</p> + +<p>You can also create a {{domxref("Blob")}} from the canvas.</p> + +<dl> + <dt>{{domxref("HTMLCanvasElement.toBlob", "canvas.toBlob(callback, type, encoderOptions)")}}</dt> + <dd>Creates a <code>Blob</code> object representing the image contained in the canvas.</dd> +</dl> + +<h2 id="延伸閱讀">延伸閱讀</h2> + +<ul> + <li>{{domxref("ImageData")}}</li> + <li><a href="/en-US/docs/Web/API/Canvas_API/Manipulating_video_using_canvas">Manipulating video using canvas</a></li> + <li><a href="https://codepo8.github.io/canvas-images-and-pixels/">Canvas, images and pixels – by Christian Heilmann</a></li> +</ul> + +<p>{{PreviousNext("Web/API/Canvas_API/Tutorial/Advanced_animations", "Web/API/Canvas_API/Tutorial/Hit_regions_and_accessibility")}}</p> diff --git a/files/zh-tw/web/api/canvas_api/tutorial/transformations/index.html b/files/zh-tw/web/api/canvas_api/tutorial/transformations/index.html new file mode 100644 index 0000000000..b25a2248dd --- /dev/null +++ b/files/zh-tw/web/api/canvas_api/tutorial/transformations/index.html @@ -0,0 +1,336 @@ +--- +title: 變形效果 +slug: Web/API/Canvas_API/Tutorial/Transformations +translation_of: Web/API/Canvas_API/Tutorial/Transformations +--- +<div>{{CanvasSidebar}} {{PreviousNext("Web/API/Canvas_API/Tutorial/Using_images", "Web/API/Canvas_API/Tutorial/Compositing")}}</div> + +<h2 id="Saving_and_restoring_state" name="Saving_and_restoring_state">畫布狀態儲存與復原</h2> + +<p>在使用變形效果等複雜繪圖方法之前，有兩個不可或缺的方法(method)必須要先了解一下:</p> + +<dl> + <dt><code>save()</code></dt> + <dd>儲存現階段畫布完整狀態。</dd> + <dt><code>restore()</code></dt> + <dd>復原最近一次儲存的畫布狀態。</dd> +</dl> + +<p>每一次呼叫save()，畫布狀態便會存進一個堆疊(stack)之中。畫布狀態包含了:</p> + +<ul> + <li>曾經套用過的變形效果，如translate, rotate和scale(稍後說明)。</li> + <li><code>strokeStyle</code>, <code>fillStyle</code>, <code>globalAlpha</code>, <code>lineWidth</code>, <code>lineCap</code>, <code>lineJoin</code>, <code>miterLimit</code>, <code>shadowOffsetX</code>, <code>shadowOffsetY</code>, <code>shadowBlur</code>, <code>shadowColor</code>, <code>globalCompositeOperation</code> 屬性的屬性值</li> + <li>目前截圖路徑(稍後說明)。</li> +</ul> + +<p>我們可以呼叫save()的次數不限，而每一次呼叫restore()，最近一次儲存的畫布狀態便會從堆疊中被取出，然後還原畫布到此畫布狀態。</p> + +<h3 id="A_save_and_restore_canvas_state_example" name="A_save_and_restore_canvas_state_example">畫布狀態儲存與復原範例</h3> + +<p>本例會畫一連串矩形圖案來說明畫布狀態堆疊是如何運作。</p> + +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + + ctx.fillRect(0,0,150,150); // Draw a rectangle with default settings + ctx.save(); // Save the default state + + ctx.fillStyle = '#09F' // Make changes to the settings + ctx.fillRect(15,15,120,120); // Draw a rectangle with new settings + + ctx.save(); // Save the current state + ctx.fillStyle = '#FFF' // Make changes to the settings + ctx.globalAlpha = 0.5; + ctx.fillRect(30,30,90,90); // Draw a rectangle with new settings + + ctx.restore(); // Restore previous state + ctx.fillRect(45,45,60,60); // Draw a rectangle with restored settings + + ctx.restore(); // Restore original state + ctx.fillRect(60,60,30,30); // Draw a rectangle with restored settings +}</pre> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" width="150" height="150"></canvas></pre> + +<pre class="brush: js">draw();</pre> +</div> + +<p> </p> + +<p>* 預設用黑色填滿這個矩形</p> + +<p>* 每種狀態可以看成是一層層堆疊的步驟紀錄</p> + +<p>第一步：畫出黑色矩形 接著把第一個狀態儲存下來(用黑色填滿)</p> + +<p>第二步：畫出藍色矩形 接著把第二個狀態儲存下來(用藍色填滿)</p> + +<p>第三步：畫出半透明矩形</p> + +<p>第四步：再畫出矩形 這時候我們取用最新儲存過的藍色(第二狀態)</p> + +<p>第五步：再畫一個矩形 我們再取出更早之前儲存的黑色(第一狀態)</p> + +<p>{{EmbedLiveSample("A_save_and_restore_canvas_state_example", "180", "180", "https://mdn.mozillademos.org/files/249/Canvas_savestate.png")}}</p> + +<h2 id="Translating" name="Translating">移動畫布</h2> + +<p><img alt="" class="internal" src="https://mdn.mozillademos.org/files/234/Canvas_grid_translate.png" style="float: right;">第一個變形效果方法是translate()。translate()是用來移動畫布，如右圖，原先畫布的原點在網格(0, 0)位置，我們可以移動畫布，使其原點移到(x, y)位置。</p> + +<dl> + <dt><code>translate(<em>x</em>, <em>y</em>)</code></dt> + <dd>移動網格上的畫布，其中x代表水平距離、y代表垂直距離。</dd> +</dl> + +<p>最好在做任何變形效果前先儲存一下畫布狀態，如此當我們需要復原先前的狀態時，只需要呼叫一下restore()即可，而且有一種情況是當我們在迴圈中移動畫布，如果不記得儲存和回復畫布狀態，繪圖區域很容易最後就超出邊界，然後出現圖案不見的狀況。</p> + +<h3 id="A_translate_example" name="A_translate_example">移動畫布範例</h3> + +<p>下面程式碼示範了利用translate()畫圖的好處，裡面，我們用了drawSpirograph()函數畫萬花筒類的圖案，如果沒有移動畫布原點，那麼每個圖案只會有四分之一會落在可視範圍，藉由移動畫布原點我們便可以自由變換每個圖案的位置，使圖案完整出現，而且省去手動計算調整每個圖案的座標位置。</p> + +<p>另外一個draw()函數透過兩個for迴圈移動畫布原點、呼叫drawSpirograph()函數、復歸畫布圓點位置共九次。</p> + +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + ctx.fillRect(0,0,300,300); + for (var i=0;i<3;i++) { + for (var j=0;j<3;j++) { + ctx.save(); + ctx.strokeStyle = "#9CFF00"; + ctx.translate(50+j*100,50+i*100); + drawSpirograph(ctx,20*(j+2)/(j+1),-8*(i+3)/(i+1),10); + ctx.restore(); + } + } +} + +function drawSpirograph(ctx,R,r,O){ + var x1 = R-O; + var y1 = 0; + var i = 1; + ctx.beginPath(); + ctx.moveTo(x1,y1); + do { + if (i>20000) break; + var x2 = (R+r)*Math.cos(i*Math.PI/72) - (r+O)*Math.cos(((R+r)/r)*(i*Math.PI/72)) + var y2 = (R+r)*Math.sin(i*Math.PI/72) - (r+O)*Math.sin(((R+r)/r)*(i*Math.PI/72)) + ctx.lineTo(x2,y2); + x1 = x2; + y1 = y2; + i++; + } while (x2 != R-O && y2 != 0 ); + ctx.stroke(); +} +</pre> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" width="300" height="300"></canvas></pre> + +<pre class="brush: js">draw();</pre> +</div> + +<p>{{EmbedLiveSample("A_translate_example", "330", "330", "https://mdn.mozillademos.org/files/256/Canvas_translate.png")}}</p> + +<h2 id="Rotating" name="Rotating">旋轉</h2> + +<p><img alt="" class="internal" src="https://mdn.mozillademos.org/files/233/Canvas_grid_rotate.png" style="float: right;">rotate()函數可以畫布原點作中心，旋轉畫布。</p> + +<dl> + <dt><code>rotate(<em>x</em>)</code></dt> + <dd>以畫布原點為中心，順時針旋轉畫布x弧度(弧度 = Math.PI * 角度 / 180)。</dd> +</dl> + +<p>我們可以呼叫translate()方法來移動旋轉中心(亦即畫布原點)。</p> + +<h3 id="A_rotate_example" name="A_rotate_example">旋轉範例</h3> + +<p>本範例我們呼叫rotate()方法來畫一系列環狀圖案。如果不用rotate()，同樣的效果也可以藉由個別計算x, y座標點(x = r*Math.cos(a); y = r*Math.sin(a))達成；呼叫rotate()和個別計算x, y座標點不同之處在於，個別計算x, y座標點只有旋轉圓形圓心，而圓形並沒有旋轉，呼叫rotate()則會旋轉圓形和圓心，不過因為我們的圖案是圓形，所以兩種作法產生的效果不會有差異。</p> + +<p>我們執行了兩個迴圈來作圖，第一個迴圈決定的圓環個數和該圓環上圓環上圓點的個數的顏色，第二個迴圈決定了圓環上圓點的個數，每一次作圖前我們都儲存了原始畫布狀態，以便結束時可以復原狀態。畫布旋轉的弧度則以圓環上圓點的個數決定，像是最內圈的圓環共有六個圓點，所以每畫一個原點，畫布就旋轉60度(360度/6)，第二的圓環有12個原點，所以畫布一次旋轉度數為30度(360度/12)，以此類推。</p> + +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + ctx.translate(75,75); + + for (var i=1;i<6;i++){ // Loop through rings (from inside to out) + ctx.save(); + ctx.fillStyle = 'rgb('+(51*i)+','+(255-51*i)+',255)'; + + for (var j=0;j<i*6;j++){ // draw individual dots + ctx.rotate(Math.PI*2/(i*6)); + ctx.beginPath(); + ctx.arc(0,i*12.5,5,0,Math.PI*2,true); + ctx.fill(); + } + + ctx.restore(); + } +} +</pre> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" width="150" height="150"></canvas></pre> + +<pre class="brush: js">draw();</pre> +</div> + +<p>{{EmbedLiveSample("A_rotate_example", "180", "180", "https://mdn.mozillademos.org/files/248/Canvas_rotate.png")}}</p> + +<h2 id="Scaling" name="Scaling">縮放</h2> + +<p>接下來這一個變形效果為縮放圖形。</p> + +<dl> + <dt>scale(x, y)</dt> + <dd>x代表縮放畫布水平網格單位x倍，y代表縮放畫布垂直網格單位y倍，輸入1.0不會造成縮放。如果輸入負值會造成座標軸鏡射，假設輸入x為-1，那麼原本畫布網格X軸上的正座標點都會變成負座標點、負座標點則變成正座標點。</dd> +</dl> + +<p>只要利用scale()，我們可以建立著名的笛卡兒座標系；執行translate(0,canvas.height)先移動畫布原點到左下角，再執行scale(1,-1)顛倒Y軸正負值，一個笛卡兒座標系便完成了。</p> + +<p>預設上畫布網格前進一單位等於前進一像素大小，所以縮小0.5倍，就會變成前進0.5的像素大小，亦即縮小圖像一半大小，反之，放大2倍將放大圖像2倍。</p> + +<h3 id="A_scale_example" name="A_scale_example">縮放範例</h3> + +<p>本程式碼範例會畫出一系列不同縮放比例的萬花筒樣式圖案。</p> + +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + ctx.strokeStyle = "#fc0"; + ctx.lineWidth = 1.5; + ctx.fillRect(0,0,300,300); + + // Uniform scaling + ctx.save() + ctx.translate(50,50); + drawSpirograph(ctx,22,6,5); + + ctx.translate(100,0); + ctx.scale(0.75,0.75); + drawSpirograph(ctx,22,6,5); + + ctx.translate(133.333,0); + ctx.scale(0.75,0.75); + drawSpirograph(ctx,22,6,5); + ctx.restore(); + + // Non uniform scaling (y direction) + ctx.strokeStyle = "#0cf"; + ctx.save() + ctx.translate(50,150); + ctx.scale(1,0.75); + drawSpirograph(ctx,22,6,5); + + ctx.translate(100,0); + ctx.scale(1,0.75); + drawSpirograph(ctx,22,6,5); + + ctx.translate(100,0); + ctx.scale(1,0.75); + drawSpirograph(ctx,22,6,5); + ctx.restore(); + + // Non uniform scaling (x direction) + ctx.strokeStyle = "#cf0"; + ctx.save() + ctx.translate(50,250); + ctx.scale(0.75,1); + drawSpirograph(ctx,22,6,5); + + ctx.translate(133.333,0); + ctx.scale(0.75,1); + drawSpirograph(ctx,22,6,5); + + ctx.translate(177.777,0); + ctx.scale(0.75,1); + drawSpirograph(ctx,22,6,5); + ctx.restore(); + +} +function drawSpirograph(ctx,R,r,O){ + var x1 = R-O; + var y1 = 0; + var i = 1; + ctx.beginPath(); + ctx.moveTo(x1,y1); + do { + if (i>20000) break; + var x2 = (R+r)*Math.cos(i*Math.PI/72) - (r+O)*Math.cos(((R+r)/r)*(i*Math.PI/72)) + var y2 = (R+r)*Math.sin(i*Math.PI/72) - (r+O)*Math.sin(((R+r)/r)*(i*Math.PI/72)) + ctx.lineTo(x2,y2); + x1 = x2; + y1 = y2; + i++; + } while (x2 != R-O && y2 != 0 ); + ctx.stroke(); +} +</pre> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" width="300" height="300"></canvas></pre> + +<pre class="brush: js">draw();</pre> +</div> + +<p>第一排第一個黃色圖案是沒有縮放的圖案，然後往右到了第二個圖案，我們程式碼中輸入了 (0.75, 0.75)的縮放倍率，到了第三個圖案，我們還是輸入了 (0.75, 0.75)的縮放倍率，而基於之前有縮小過一次，所以第三個圖案相對於第一個沒有縮放的圖案是0.75 × 0.75 = 0.5625倍。</p> + +<p>第二排藍色圖案我們只改變Y軸的縮放倍率，X軸維持不變，因而產生一個比一個更扁的橢圓圖形。同理，第三排綠色圖案改變X軸的縮放倍率，Y軸維持不變。</p> + +<p>{{EmbedLiveSample("A_scale_example", "330", "330", "https://mdn.mozillademos.org/files/250/Canvas_scale.png")}}</p> + +<h2 id="Transforms" name="Transforms">變形</h2> + +<p>最後一個方法是設定變形矩陣，藉由改變變形矩陣，我們因此可以營造各種變形效果；其實先前所提到的rotate, translate, scale都是在設定變形矩陣，而這邊的這個方法就是直接去改變變形矩陣。</p> + +<dl> + <dt><code>transform(<em>m11</em>, <em>m12</em>, <em>m21</em>, <em>m22</em>, <em>dx</em>, <em>dy</em>)</code></dt> + <dd>呼叫Transform會拿目前的變形矩陣乘以下列矩陣:</dd> + <dd><img src="http://www.numberempire.com/equation.render?%5Cbegin{bmatrix}%20m11%20&%20m21%20%5C%5C%20m12%20&%20m22%5Cend{bmatrix}%5Cbegin{bmatrix}%20x%20%5C%5C%20y%5Cend{bmatrix}"></dd> + <dd> + <pre>m11 m21 dx +m12 m22 dy +0 0 1 +</pre> + </dd> +</dl> + +<dl> + <dd>運算後的新矩陣將取代目前的變形矩陣。</dd> + <dd>其中m11代表水平縮放圖像，m12代表水平偏移圖像，m21代表垂直偏移圖像，m22代表垂直縮放圖像，dx代表水平移動圖像，dy代表垂直移動圖像。</dd> + <dd>如果輸入<code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity" title="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity">Infinity</a></code> 值，不會引起例外錯誤，矩陣值會依照輸入設成無限。</dd> + <dt><code>setTransform(<em>m11</em>, <em>m12</em>, <em>m21</em>, <em>m22</em>, <em>dx</em>, <em>dy</em>)</code></dt> + <dd>復原目前矩陣為恆等矩陣(Identiy matrix，也就是預設矩陣)，然後再以輸入參數呼叫transform()。</dd> +</dl> + +<h3 id="transform_.2F_setTransform_examples" name="transform_.2F_setTransform_examples"><code>transform</code> / <code>setTransform</code>範例</h3> + +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + + var sin = Math.sin(Math.PI/6); + var cos = Math.cos(Math.PI/6); + ctx.translate(100, 100); + var c = 0; + for (var i=0; i <= 12; i++) { + c = Math.floor(255 / 12 * i); + ctx.fillStyle = "rgb(" + c + "," + c + "," + c + ")"; + ctx.fillRect(0, 0, 100, 10); + ctx.transform(cos, sin, -sin, cos, 0, 0); + } + + ctx.setTransform(-1, 0, 0, 1, 100, 100); + ctx.fillStyle = "rgba(255, 128, 255, 0.5)"; + ctx.fillRect(0, 50, 100, 100); +} +</pre> + +<div class="hidden"> +<pre class="brush: html"><canvas id="canvas" width="200" height="250"></canvas></pre> + +<pre class="brush: js">draw();</pre> +</div> + +<p>{{EmbedLiveSample("transform_.2F_setTransform_examples", "230", "280", "https://mdn.mozillademos.org/files/255/Canvas_transform.png")}}</p> + +<p>{{PreviousNext("Web/Guide/HTML/Canvas_tutorial/Applying_styles_and_colors", "Web/Guide/HTML/Canvas_tutorial/Compositing")}}</p> diff --git a/files/zh-tw/web/api/canvas_api/tutorial/using_images/index.html b/files/zh-tw/web/api/canvas_api/tutorial/using_images/index.html new file mode 100644 index 0000000000..7bb6bf791f --- /dev/null +++ b/files/zh-tw/web/api/canvas_api/tutorial/using_images/index.html @@ -0,0 +1,342 @@ +--- +title: 使用影像 +slug: Web/API/Canvas_API/Tutorial/Using_images +translation_of: Web/API/Canvas_API/Tutorial/Using_images +--- +<div>{{CanvasSidebar}} {{PreviousNext("Web/API/Canvas_API/Tutorial/Drawing_text", "Web/API/Canvas_API/Tutorial/Transformations" )}}</div> + +<p><font face="DejaVu Sans"><span lang="zh-TW"><font face="DejaVu Sans, sans-serif">使用影像是</font></span></font>{{HTMLElement("canvas")}}<font face="DejaVu Sans"><span lang="zh-TW"><font face="DejaVu Sans, sans-serif">另一個有趣的功能，這個功能可以用來動態組合圖片或作為背景等等。任何瀏覽器支援的外部圖片格式都可以使用，例如</font></span></font><font face="DejaVu Sans, sans-serif">PNG, GIF, </font><font face="DejaVu Sans"><span lang="zh-TW"><font face="DejaVu Sans, sans-serif">或</font></span></font><font face="DejaVu Sans, sans-serif">JPEG</font><font face="DejaVu Sans"><span lang="zh-TW"><font face="DejaVu Sans, sans-serif">，甚至也可以利用同一份頁面上其他畫布元素產生的影像.</font></span></font></p> + +<p><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">載入影像到畫布中基本上需要兩個步驟：</span></font></p> + +<ol> + <li> + <p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">取得</span></font><font face="DejaVu Sans, sans-serif">{{domxref("HTMLImageElement")}}</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">物件或其他畫布元素的參照</span></font><font face="DejaVu Sans, sans-serif">(reference)</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">作為來源，透過單純提供</span></font><font face="DejaVu Sans, sans-serif">URL</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">或圖片位置的方式是行不通的</span></font>.</p> + </li> + <li> + <p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">用</span></font><font face="DejaVu Sans, sans-serif">drawImage()</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">函數在畫布上畫影像</span></font>.</p> + </li> +</ol> + +<p><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">接下來便來看看要怎麼做</span></font>.</p> + +<h2 id="取得影像"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">取得影像</span></font></h2> + +<p><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">畫布</span></font><font face="DejaVu Sans, sans-serif">API</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">能接受以下資料型態作為影像來源</span></font>:</p> + +<dl> + <dt>{{domxref("HTMLImageElement")}}</dt> + <dd> + <p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">用</span></font><font face="DejaVu Sans, sans-serif">Image()</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">建構成的影像或是</span></font><font face="DejaVu Sans, sans-serif">{{HTMLElement("img")}}</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">元素</span></font>.</p> + </dd> + <dt>{{domxref("HTMLVideoElement")}}</dt> + <dd> + <p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">用</span></font><font face="DejaVu Sans, sans-serif">{{domxref("HTMLVideoElement")}}</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">元素作影像來源，抓取影片目前的影像畫格當作影像使用</span></font>.</p> + </dd> + <dt>{{domxref("HTMLCanvasElement")}}</dt> + <dd> + <p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">用另一個</span></font><font face="DejaVu Sans, sans-serif">{{domxref("HTMLCanvasElement")}}</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">元素當影像來源</span></font>.</p> + </dd> + <dt>{{domxref("ImageBitmap")}}</dt> + <dd> + <p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">可以被快速渲染的點陣圖</span></font><font face="DejaVu Sans, sans-serif">(bitmap)</font><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">，點陣圖能由上述所有來源產生</span></font>.</p> + </dd> +</dl> + +<p><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">這些來源統一參照</span></font> <font face="DejaVu Sans, sans-serif"><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#image-sources-for-2d-rendering-contexts" title="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#image-sources-for-2d-rendering-contexts">CanvasImageSource</a><span lang="zh-TW">型態</span></font>.</p> + +<p style="margin-bottom: 0in;"><font face="DejaVu Sans, sans-serif"><span lang="zh-TW">有好幾種方法能夠取得影像用於畫布<font face="DejaVu Sans, sans-serif">.</font></span></font></p> + +<p style="margin-bottom: 0in;"> </p> + +<h3 id="使用同一份網頁上的影像">使用同一份網頁上的影像</h3> + +<p>我們能透過下面幾個方法取得影像:</p> + +<ul> + <li>從{{domxref("document.images")}}</li> + <li>{{domxref("document.getElementsByTagName()")}}方法</li> + <li>如果知道特定影像的ID，那可以{{domxref("document.getElementById()")}}方法</li> +</ul> + +<h3 id="使用來自其他網域的影像">使用來自其他網域的影像</h3> + +<p>Using the <a href="/en-US/docs/HTML/CORS_settings_attributes" rel="internal" title="CORS settings attributes"><code>crossOrigin</code></a> attribute on an 透過{{HTMLElement("HTMLImageElement")}}的<a href="/en-US/docs/HTML/CORS_settings_attributes" rel="internal" title="CORS settings attributes"><code>crossOrigin</code></a>屬性, 我們可以要求從另一個網域載入影像來使用，若是寄存網域(thehosting domain)准許跨網路存取該影像，那麼我們便可以使用它而不用污染(taint)我們的畫布，反之，使用該影像會污染畫布(<a href="https://developer.mozilla.org/en-US/docs/HTML/CORS_Enabled_Image#What_is_a_.22tainted.22_canvas.3F" rel="internal" title="en/CORS_Enabled_Image#What_is_a_.22tainted.22_canvas.3F">taint the canvas</a>)。</p> + +<h3 id="使用其他畫布元素">使用其他畫布元素</h3> + +<p>如同取得其他影像，我們一樣能用{{domxref("document.getElementsByTagName()")}}或{{domxref("document.getElementById()")}}方法取得其他畫布元素，但是在使用之前請記得來源畫布上已經有繪上圖了。</p> + +<p>使用其他畫布元素作為影像來源有很多有用的應用用途，其中之一便是建立第二個小畫布作為另一個大畫布的縮小影像.</p> + +<h3 id="創造全新的影像">創造全新的影像</h3> + +<p>產生新的{{domxref("HTMLImageElement")}}物件也能當作影像來源，這邊，我們可以用Image()來建構一個新影像元素:</p> + +<pre class="brush: js">var img = new Image(); // Create new img element +img.src = 'myImage.png'; // Set source path +</pre> + +<p>上述程式碼執行後會載入影像.</p> + +<p>在影像載入完成前呼叫drawImage()不會有任何效果，甚至某些瀏覽器還會拋出例外狀況，所以應該要透過利用載入事件來避免這類問題:</p> + +<pre class="brush: js">var img = new Image(); // Create new img element +img.addEventListener("load", function() { + // execute drawImage statements here +}, false); +img.src = 'myImage.png'; // Set source path +</pre> + +<p>若是只要載入一份影像，可以用上面的方法，不過當需要載入、追蹤多個影像時，我們就需要更好的方法了，雖然管理多個影像載入已經超出本教學的範疇，然而如果有興趣的話，可以參考<a class="external" href="http://www.webreference.com/programming/javascript/gr/column3/" rel="external" title="http://www.webreference.com/programming/javascript/gr/column3/">JavaScript Image Preloader</a>這份文件.</p> + +<h3 id="以dataURL嵌入影像">以data:URL嵌入影像</h3> + +<p>另一個載入影像的方法是利用<a class="external" href="/en-US/docs/data_URIs" rel="external" title="http://en.wikipedia.org/wiki/Data:_URL">data: url</a>，透過data URL可以直接將影像定義成Base64編碼的字串，然後嵌入程式碼之中.</p> + +<pre class="js">var img_src = 'data:image/gif;base64,R0lGODlhCwALAIAAAAAA3pn/ZiH5BAEAAAEALAAAAAALAAsAAAIUhA+hkcuO4lmNVindo7qyrIXiGBYAOw=='; +</pre> + +<p>data URL的好處之一是立即產生影像而不用再和伺服器連線，另一個好處是這樣便能夠將影像包入你的<a href="/en-US/docs/Web/CSS" title="/en-US/docs/Web/CSS">CSS</a>, <a href="/en-US/docs/Web/JavaScript" title="/en-US/docs/Web/JavaScript">JavaScript</a>, <a href="/en-US/docs/Web/HTML" title="/en-US/docs/Web/HTML">HTML</a>之中，讓影像更具可攜性.</p> + +<p>壞處則是影像將不會被快取起來，而且對大影像來說編碼後的URL會很長.</p> + +<h3 id="Using_frames_from_a_video">Using frames from a video</h3> + +<p>我們還能夠使用{{HTMLElement("video")}}元素中的影片的影片畫格(縱使影片為隱藏)，例如，現在我們有一個ID為”myvideo” 的{{HTMLElement("video")}}元素:</p> + +<pre class="brush: js">function getMyVideo() { + var canvas = document.getElementById('canvas'); + if (canvas.getContext) { + var ctx = canvas.getContext('2d'); + + return document.getElementById('myvideo'); + } +} +</pre> + +<p>上面的方法會回傳一個{{domxref("HTMLVideoElement")}}的影像物件，如前所述，這個物件可以被視為CanvasImageSource類別的物件來使用。<br> + 關於如何利用<video>元素於畫布上的進階說明，可以參考html5Doctor的“<a href="http://html5doctor.com/video-canvas-magic/" title="http://html5doctor.com/video-canvas-magic/">video + canvas = magic</a>”一文.</p> + +<h2 id="影像繪圖">影像繪圖</h2> + +<p>一旦我們取得來源影像物件的參照(reference)，便可以用drawImage()方法將影像渲染到畫布上，drawImage()方法是一個多載(overload)方法，有數個型態，待會我們會看到這項特性，現在我們先來看drawImage()最基本的型態:</p> + +<dl> + <dt><code>drawImage(<em>image</em>, <em>x</em>, <em>y</em>)</code></dt> + <dd>從座標點(x, y)開始畫上image參數指定的來源影像(CanvasImageSource).</dd> +</dl> + +<h3 id="範例_一條簡單的線段影像">範例: 一條簡單的線段影像</h3> + +<p>這個範例會使用外部影像作為一個小型線圖的背景。利用預先劃好的圖作為背景的話就不用再靠程式來產生背景，如此一來可以顯著地減少程式碼。下面藉由影像物件的load事件處理器來處理繪圖作業，其中drawImage()方法把背景圖片放置在畫布左上角，座標點(0, 0)位置.</p> + +<div class="hidden"> +<pre class="brush: html"><html> + <body onload="draw();"> + <canvas id="canvas" width="180" height="150"></canvas> + </body> +</html> +</pre> +</div> + +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + var img = new Image(); + img.onload = function(){ + ctx.drawImage(img,0,0); + ctx.beginPath(); + ctx.moveTo(30,96); + ctx.lineTo(70,66); + ctx.lineTo(103,76); + ctx.lineTo(170,15); + ctx.stroke(); + }; + img.src = 'https://mdn.mozillademos.org/files/5395/backdrop.png'; +}</pre> + +<p>結果如下:</p> + +<p>{{EmbedLiveSample("Example.3A_A_simple_line_graph", 220, 160, "https://mdn.mozillademos.org/files/206/Canvas_backdrop.png")}}</p> + +<h2 id="縮放">縮放</h2> + +<p>drawImage()的第二個型態增加了兩個新參數，讓我們在畫布上放置影像的同時並縮放影像.</p> + +<dl> + <dt><code>drawImage(<em>image</em>, <em>x</em>, <em>y</em>, <em>width</em>, <em>height</em>)</code></dt> + <dd>當放置影像於畫布上時，會按照參數width(寬)、height(高)來縮放影像.</dd> +</dl> + +<h3 id="範例_排列影像">範例: 排列影像</h3> + +<p>本例我們會取一張影像作為桌布，然後透過簡單的迴圈來重複縮放、貼上影像於畫布上。在程式碼中，第一個迴圈走一遍每一列，第二個迴圈走一遍每一行，影像則縮小成原始影像的三分之一，50 x 38像素.</p> + +<div class="note"> +<p><strong>Note</strong>: 過度縮放影像可能會造成影像模糊或產生顆粒感，所以如果影像中有文字需要閱讀，最好不要縮放影像.</p> +</div> + +<div class="hidden"> +<pre class="brush: html"><html> + <body onload="draw();"> + <canvas id="canvas" width="150" height="150"></canvas> + </body> +</html> +</pre> +</div> + +<pre class="brush: js">function draw() { + var ctx = document.getElementById('canvas').getContext('2d'); + var img = new Image(); + img.onload = function(){ + for (var i=0;i<4;i++){ + for (var j=0;j<3;j++){ + ctx.drawImage(img,j*50,i*38,50,38); + } + } + }; + img.src = 'https://mdn.mozillademos.org/files/5397/rhino.jpg'; +}</pre> + +<p>結果如下:</p> + +<p>{{EmbedLiveSample("Example.3A_Tiling_an_image", 160, 160, "https://mdn.mozillademos.org/files/251/Canvas_scale_image.png")}}</p> + +<h2 id="切割影像">切割影像</h2> + +<p>drawImage()第三個型態接受9個參數，其中8個讓我們從原始影像中切出一部分影像、縮放並畫到畫布上.</p> + +<dl> + <dt><code>drawImage(<em>image</em>, <em>sx</em>, <em>sy</em>, <em>sWidth</em>, <em>sHeight</em>, <em>dx</em>, <em>dy</em>, <em>dWidth</em>, <em>dHeight</em>)</code></dt> + <dd>image參數是來源影像物件，(sx, sy)代表在來源影像中以(sx, sy)座標點作為切割的起始點，sWidth和sHeight代表切割寬和高，(dx, dy)代表放到畫布上的座標點，dWidth和dHeight代表縮放影像至指定的寬和高.</dd> +</dl> + +<p><img alt="" class="internal" src="https://mdn.mozillademos.org/files/225/Canvas_drawimage.jpg" style="float: right; height: 290px; width: 300px;">請參照右圖，前四個參數定義了在來源影像上切割的起始點和切割大小，後四個參數定義了畫到畫布上的位置和影像大小.</p> + +<p>切割是一個很有用的工具，我們可以把所有影像放到一張影像上，然後利用切割來組成最終完整的影像，比如說，我們可以把所有需要用來組成一張圖表的文字放到一張PNG圖檔內，之後只需要單純地再依據資料來縮放圖表，另外，我們也不用多次載入多張影像，這樣對提升載入影像效能頗有幫助.</p> + +<p> </p> + +<p> </p> + +<h3 id="範例_畫一個有畫框的影像">範例: 畫一個有畫框的影像</h3> + +<p>本例用和前一個範例一樣的犀牛圖，然後切出犀牛頭部影像部分再放入一個影像畫框，這個影像畫框是一個有陰影的24位元PNG圖檔，因為24位元PNG影像具備完整的8位元不透明色版(alpha channel)，所以不像GIF影像和8位元PNG影像，它能夠放任何背景之上而無須擔心產生消光色(matte color).</p> + +<pre class="brush: html"><html> + <body onload="draw();"> + <canvas id="canvas" width="150" height="150"></canvas> + <div style="display:none;"> + <img id="source" src="https://mdn.mozillademos.org/files/5397/rhino.jpg" width="300" height="227"> + <img id="frame" src="https://mdn.mozillademos.org/files/242/Canvas_picture_frame.png" width="132" height="150"> + </div> + </body> +</html> +</pre> + +<pre class="brush: js">function draw() { + var canvas = document.getElementById('canvas'); + var ctx = canvas.getContext('2d'); + + // Draw slice + ctx.drawImage(document.getElementById('source'), + 33, 71, 104, 124, 21, 20, 87, 104); + + // Draw frame + ctx.drawImage(document.getElementById('frame'),0,0); +}</pre> + +<p>這次我們不產生新的{{domxref("HTMLImageElement")}}物件，改採用直接把影像包入HTML的{{HTMLElement("img")}}標籤，然後再取得影像元素，其中HTML上的影像已經透過設定CSS屬性{{cssxref("display")}}為none來隱藏起來了.</p> + +<p>{{EmbedLiveSample("Example.3A_Framing_an_image", 160, 160, "https://mdn.mozillademos.org/files/226/Canvas_drawimage2.jpg")}}</p> + +<p>程式碼相當簡單，每個{{HTMLElement("img")}}有自己的ID屬性，這樣便可以利用{{domxref("document.getElementById()")}}輕易取得，之後再簡單地用drawImage()方法切割犀牛影像然後縮放並放到畫布上，最後第二個drawImage()再把畫框放到上面.</p> + +<h2 id="畫廊範例">畫廊範例</h2> + +<p>在本章的最後一個範例，我們將建造一個小畫廊。當網頁載入完成時，我們會為每一張影像產生一個{{HTMLElement("canvas")}}元素，並且加上畫框.</p> + +<p>本範例中，每一張影像的寬高是固定的，畫框也是一樣，你可以嘗試看看改進程式碼，依據影像的寬高來設定畫框，使畫框能剛剛好框住影像.</p> + +<p>從下方的程式碼範例可以很清楚看到，我們為{{domxref("document.images")}}容器內的影像，一張一張地新建畫布，其中，對於不熟悉文件物件模型 (DOM)的人來說，大慨比較值得注意之處在於使用到{{domxref("Node.insertBefore")}} 方法；insertBefore()是影像元素的父節點(亦即<td>元素)的一個方法，這個方法會把新畫布元素插入於影像元素之前.</p> + +<pre class="brush: html"><html> + <body onload="draw();"> + <table> + <tr> + <td><img src="https://mdn.mozillademos.org/files/5399/gallery_1.jpg"></td> + <td><img src="https://mdn.mozillademos.org/files/5401/gallery_2.jpg"></td> + <td><img src="https://mdn.mozillademos.org/files/5403/gallery_3.jpg"></td> + <td><img src="https://mdn.mozillademos.org/files/5405/gallery_4.jpg"></td> + </tr> + <tr> + <td><img src="https://mdn.mozillademos.org/files/5407/gallery_5.jpg"></td> + <td><img src="https://mdn.mozillademos.org/files/5409/gallery_6.jpg"></td> + <td><img src="https://mdn.mozillademos.org/files/5411/gallery_7.jpg"></td> + <td><img src="https://mdn.mozillademos.org/files/5413/gallery_8.jpg"></td> + </tr> + </table> + <img id="frame" src="https://mdn.mozillademos.org/files/242/Canvas_picture_frame.png" width="132" height="150"> + </body> +</html> +</pre> + +<p>這些是一些設定樣式的CSS:</p> + +<pre class="brush: css">body { + background: 0 -100px repeat-x url(https://mdn.mozillademos.org/files/5415/bg_gallery.png) #4F191A; + margin: 10px; +} + +img { + display: none; +} + +table { + margin: 0 auto; +} + +td { + padding: 15px; +} +</pre> + +<p>綜合起來這就是建造出我們小畫廊的程式碼:</p> + +<pre class="brush: js">function draw() { + + // Loop through all images + for (var i=0;i<document.images.length;i++){ + + // Don't add a canvas for the frame image + if (document.images[i].getAttribute('id')!='frame'){ + + // Create canvas element + canvas = document.createElement('canvas'); + canvas.setAttribute('width',132); + canvas.setAttribute('height',150); + + // Insert before the image + document.images[i].parentNode.insertBefore(canvas,document.images[i]); + + ctx = canvas.getContext('2d'); + + // Draw image to canvas + ctx.drawImage(document.images[i],15,20); + + // Add frame + ctx.drawImage(document.getElementById('frame'),0,0); + } + } +}</pre> + +<p>{{EmbedLiveSample("Art_gallery_example", 725, 400, "https://mdn.mozillademos.org/files/205/Canvas_art_gallery.jpg")}}</p> + +<h2 id="控制影像縮放行為">控制影像縮放行為</h2> + +<p>如前所述，縮放影像會導致影像模糊化或是顆粒化，你可以嘗試透過繪圖環境的imageSmoothingEnabled屬性來控制影像平滑演算法的使用，預設上這個屬性的值為true，也就是說當縮放時，影像會經過平滑處理。如果要關掉這個功能，你可以這麼做:</p> + +<pre class="js">ctx.mozImageSmoothingEnabled = false; +</pre> + +<p>{{PreviousNext("Web/Guide/HTML/Canvas_tutorial/Drawing_shapes", "Web/Guide/HTML/Canvas_tutorial/Applying_styles_and_colors")}}</p> diff --git a/files/zh-tw/web/api/canvasrenderingcontext2d/clearrect/index.html b/files/zh-tw/web/api/canvasrenderingcontext2d/clearrect/index.html new file mode 100644 index 0000000000..e5792ffade --- /dev/null +++ b/files/zh-tw/web/api/canvasrenderingcontext2d/clearrect/index.html @@ -0,0 +1,189 @@ +--- +title: CanvasRenderingContext2D.clearRect() +slug: Web/API/CanvasRenderingContext2D/clearRect +translation_of: Web/API/CanvasRenderingContext2D/clearRect +--- +<div>{{APIRef}}</div> + +<p>Canvas 2D API 的 <code><strong>CanvasRenderingContext2D</strong></code><strong><code>.clearRect()</code></strong> 方法可以設定指定矩形（經由坐標 <em>(x, y)</em> 及大小 <em>(width, height)</em>）範圍內的所有像素為透明，清除所有先前繪製的內容。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">void <var><em>ctx</em>.clearRect(x, y, width, height);</var> +</pre> + +<h3 id="參數">參數</h3> + +<dl> + <dt><code>x</code></dt> + <dd>The x axis of the coordinate for the rectangle starting point.</dd> + <dt><code>y</code></dt> + <dd>The y axis of the coordinate for the rectangle starting point.</dd> + <dt><code>width</code></dt> + <dd>The rectangle's width.</dd> + <dt><code>height</code></dt> + <dd>The rectangle's height.</dd> +</dl> + +<h2 id="Usage_notes">Usage notes</h2> + +<p>A common problem with <code>clearRect</code> is that it may appear it does not work when not <a href="/en-US/docs/Web/API/Canvas_API/Tutorial/Drawing_shapes#Drawing_paths">using paths properly</a>. Don't forget to call {{domxref("CanvasRenderingContext2D.beginPath", "beginPath()")}} before starting to draw the new frame after calling <code>clearRect</code>.</p> + +<h2 id="範例">範例</h2> + +<h3 id="Using_the_clearRect_method">Using the <code>clearRect</code> method</h3> + +<p>This is just a simple code snippet which uses the <code>clearRect</code> method.</p> + +<h4 id="HTML">HTML</h4> + +<pre class="brush: html"><canvas id="canvas"></canvas> +</pre> + +<h4 id="JavaScript">JavaScript</h4> + +<pre class="brush: js; highlight:[11]">var canvas = document.getElementById('canvas'); +var ctx = canvas.getContext('2d'); + +ctx.beginPath(); +ctx.moveTo(20, 20); +ctx.lineTo(200, 20); +ctx.lineTo(120, 120); +ctx.closePath(); // draws last line of the triangle +ctx.stroke(); + +ctx.clearRect(10, 10, 100, 100); + +// clear the whole canvas +// ctx.clearRect(0, 0, canvas.width, canvas.height); +</pre> + +<p>Edit the code below and see your changes update live in the canvas:</p> + +<div style="display: none;"> +<h6 id="Playable_code">Playable code</h6> + +<pre class="brush: html"><canvas id="canvas" width="400" height="200" class="playable-canvas"></canvas> +<div class="playable-buttons"> + <input id="edit" type="button" value="Edit" /> + <input id="reset" type="button" value="Reset" /> +</div> +<textarea id="code" class="playable-code" style="height:140px;"> +ctx.beginPath(); +ctx.moveTo(20,20); +ctx.lineTo(200,20); +ctx.lineTo(120,120); +ctx.closePath(); // draws last line of the triangle +ctx.stroke(); + +ctx.clearRect(10, 10, 100, 100);</textarea> +</pre> + +<pre class="brush: js">var canvas = document.getElementById("canvas"); +var ctx = canvas.getContext("2d"); +var textarea = document.getElementById("code"); +var reset = document.getElementById("reset"); +var edit = document.getElementById("edit"); +var code = textarea.value; + +function drawCanvas() { + ctx.clearRect(0, 0, canvas.width, canvas.height); + eval(textarea.value); +} + +reset.addEventListener("click", function() { + textarea.value = code; + drawCanvas(); +}); + +edit.addEventListener("click", function() { + textarea.focus(); +}) + +textarea.addEventListener("input", drawCanvas); +window.addEventListener("load", drawCanvas); +</pre> +</div> + +<p>{{ EmbedLiveSample('Playable_code', 700, 400) }}</p> + +<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('HTML WHATWG', "scripting.html#dom-context-2d-clearrect", "CanvasRenderingContext2D.clearRect")}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li>The interface defining it, {{domxref("CanvasRenderingContext2D")}}</li> + <li>{{domxref("CanvasRenderingContext2D.fillRect()")}}</li> + <li>{{domxref("CanvasRenderingContext2D.strokeRect()")}}</li> +</ul> diff --git a/files/zh-tw/web/api/canvasrenderingcontext2d/index.html b/files/zh-tw/web/api/canvasrenderingcontext2d/index.html new file mode 100644 index 0000000000..31aa34ecdf --- /dev/null +++ b/files/zh-tw/web/api/canvasrenderingcontext2d/index.html @@ -0,0 +1,459 @@ +--- +title: CanvasRenderingContext2D +slug: Web/API/CanvasRenderingContext2D +translation_of: Web/API/CanvasRenderingContext2D +--- +<div>{{APIRef}}</div> + +<div><strong>CanvasRenderingContext2D</strong> 介面被使用於繪製矩形、文字、影像以及其它基於 canvas 元素的物件。此介面提供了繪製 {{ HTMLElement("canvas") }} 元素外觀的 2D 渲染環境。</div> + +<div> </div> + +<p>要取得此實作此介面的實體物件，可以於一個 <code><canvas></code> 元素上以 "2d" 為參數呼叫 {{domxref("HTMLCanvasElement.getContext()", "getContext()")}} 方法：</p> + +<pre class="brush: js">var canvas = document.getElementById('mycanvas'); // in your HTML this element appears as <canvas id="mycanvas"></canvas> +var ctx = canvas.getContext('2d'); +</pre> + +<p>只要你有了 canvas 的 2D 繪製背景物件，你就可以在其中繪圖。 舉個例子：</p> + +<pre class="brush: js">ctx.fillStyle = "rgb(200,0,0)"; // sets the color to fill in the rectangle with +ctx.fillRect(10, 10, 55, 50); // draws the rectangle at position 10, 10 with a width of 55 and a height of 50 +</pre> + +<p><a href="/zh-TW/docs/Web/API/Canvas_API/Tutorial">canvas 教學</a>有更多資訊、範例，以及資源。</p> + +<h2 id="繪製矩形">繪製矩形</h2> + +<p>有三個函式可以馬上在點陣圖上畫出長方形。</p> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.clearRect()")}}</dt> + <dd>Sets all pixels in the rectangle defined by starting point <em>(x, y)</em> and size <em>(width, height)</em> to transparent black, erasing any previously drawn content.</dd> + <dt>{{domxref("CanvasRenderingContext2D.fillRect()")}}</dt> + <dd>Draws a filled rectangle at <em>(x, y) </em>position whose size is determined by <em>width</em> and <em>height</em>.</dd> + <dt>{{domxref("CanvasRenderingContext2D.strokeRect()")}}</dt> + <dd>Paints a rectangle which has a starting point at <em>(x, y)</em> and has a<em> w</em> width and an <em>h</em> height onto the canvas, using the current stroke style.</dd> +</dl> + +<h2 id="繪製文字">繪製文字</h2> + +<p>The following methods are provided for drawing text. See also the {{domxref("TextMetrics")}} object for text properties.</p> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.fillText()")}}</dt> + <dd>Draws (fills) a given text at the given (x,y) position.</dd> + <dt>{{domxref("CanvasRenderingContext2D.strokeText()")}}</dt> + <dd>Draws (strokes) a given text at the given <em>(x, y) </em>position.</dd> + <dt>{{domxref("CanvasRenderingContext2D.measureText()")}}</dt> + <dd>Returns a {{domxref("TextMetrics")}} object.</dd> +</dl> + +<h2 id="線條樣式">線條樣式</h2> + +<p>The following methods and properties control how lines are drawn.</p> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.lineWidth")}}</dt> + <dd>Width of lines. Default <code>1.0</code></dd> + <dt>{{domxref("CanvasRenderingContext2D.lineCap")}}</dt> + <dd>Type of endings on the end of lines. Possible values: <code>butt</code> (default), <code>round</code>, <code>square</code>.</dd> + <dt>{{domxref("CanvasRenderingContext2D.lineJoin")}}</dt> + <dd>Defines the type of corners where two lines meet. Possible values: <code>round</code>, <code>bevel</code>, <code>miter</code> (default).</dd> + <dt>{{domxref("CanvasRenderingContext2D.miterLimit")}}</dt> + <dd>Miter limit ratio. Default <code>10</code>.</dd> + <dt>{{domxref("CanvasRenderingContext2D.getLineDash()")}}</dt> + <dd>Returns the current line dash pattern array containing an even number of non-negative numbers.</dd> + <dt>{{domxref("CanvasRenderingContext2D.setLineDash()")}}</dt> + <dd>Sets the current line dash pattern.</dd> + <dt>{{domxref("CanvasRenderingContext2D.lineDashOffset")}}</dt> + <dd>Specifies where to start a dash array on a line.</dd> +</dl> + +<h2 id="文字樣式">文字樣式</h2> + +<p>The following properties control how text is laid out.</p> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.font")}}</dt> + <dd>Font setting. Default value <code>10px sans-serif</code>.</dd> + <dt>{{domxref("CanvasRenderingContext2D.textAlign")}}</dt> + <dd>Text alignment setting. Possible values: <code>start</code> (default), <code>end</code>, <code>left</code>, <code>right</code> or <code>center</code>.</dd> + <dt>{{domxref("CanvasRenderingContext2D.textBaseline")}}</dt> + <dd>Baseline alignment setting. Possible values: <code>top</code>, <code>hanging</code>, <code>middle</code>, <code>alphabetic</code> (default), <code>ideographic</code>, <code>bottom</code>.</dd> + <dt>{{domxref("CanvasRenderingContext2D.direction")}}</dt> + <dd>Directionality. Possible values: <code>ltr, rtl</code>, <code>inherit</code> (default).</dd> +</dl> + +<h2 id="填充及邊線樣式">填充及邊線樣式</h2> + +<p>Fill styling is used for colors and styles inside shapes and stroke styling is used for the lines around shapes.</p> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.fillStyle")}}</dt> + <dd>Color or style to use inside shapes. Default <code>#000</code> (black).</dd> + <dt>{{domxref("CanvasRenderingContext2D.strokeStyle")}}</dt> + <dd>Color or style to use for the lines around shapes. Default <code>#000</code> (black).</dd> +</dl> + +<h2 id="漸層填色及圖案填充">漸層填色及圖案填充</h2> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.createLinearGradient()")}}</dt> + <dd>Creates a linear gradient along the line given by the coordinates represented by the parameters.</dd> + <dt>{{domxref("CanvasRenderingContext2D.createRadialGradient()")}}</dt> + <dd>Creates a radial gradient given by the coordinates of the two circles represented by the parameters.</dd> + <dt>{{domxref("CanvasRenderingContext2D.createPattern()")}}</dt> + <dd>Creates a pattern using the specified image (a {{domxref("CanvasImageSource")}}). It repeats the source in the directions specified by the repetition argument. This method returns a {{domxref("CanvasPattern")}}.</dd> +</dl> + +<h2 id="陰影">陰影</h2> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.shadowBlur")}}</dt> + <dd>Specifies the blurring effect. Default <code>0</code></dd> + <dt>{{domxref("CanvasRenderingContext2D.shadowColor")}}</dt> + <dd>Color of the shadow. Default fully-transparent black.</dd> + <dt>{{domxref("CanvasRenderingContext2D.shadowOffsetX")}}</dt> + <dd>Horizontal distance the shadow will be offset. Default 0.</dd> + <dt>{{domxref("CanvasRenderingContext2D.shadowOffsetY")}}</dt> + <dd>Vertical distance the shadow will be offset. Default 0.</dd> +</dl> + +<h2 id="路徑">路徑</h2> + +<p>The following methods can be used to manipulate paths of objects.</p> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.beginPath()")}}</dt> + <dd>Starts a new path by emptying the list of sub-paths. Call this method when you want to create a new path.</dd> + <dt>{{domxref("CanvasRenderingContext2D.closePath()")}}</dt> + <dd>Causes the point of the pen to move back to the start of the current sub-path. It tries to draw a straight line from the current point to the start. If the shape has already been closed or has only one point, this function does nothing.</dd> + <dt>{{domxref("CanvasRenderingContext2D.moveTo()")}}</dt> + <dd>Moves the starting point of a new sub-path to the <strong>(x, y)</strong> coordinates.</dd> + <dt>{{domxref("CanvasRenderingContext2D.lineTo()")}}</dt> + <dd>Connects the last point in the subpath to the <code>x, y</code> coordinates with a straight line.</dd> + <dt>{{domxref("CanvasRenderingContext2D.bezierCurveTo()")}}</dt> + <dd>Adds a cubic Bézier curve to the path. It requires three points. The first two points are control points and the third one is the end point. The starting point is the last point in the current path, which can be changed using <code>moveTo()</code> before creating the Bézier curve.</dd> + <dt>{{domxref("CanvasRenderingContext2D.quadraticCurveTo()")}}</dt> + <dd>Adds a quadratic Bézier curve to the current path.</dd> + <dt>{{domxref("CanvasRenderingContext2D.arc()")}}</dt> + <dd>Adds an arc to the path which is centered at <em>(x, y)</em> position with radius<em> r</em> starting at <em>startAngle</em> and ending at <em>endAngle</em> going in the given direction by <em>anticlockwise</em> (defaulting to clockwise).</dd> + <dt>{{domxref("CanvasRenderingContext2D.arcTo()")}}</dt> + <dd>Adds an arc to the path with the given control points and radius, connected to the previous point by a straight line.</dd> + <dt>{{domxref("CanvasRenderingContext2D.ellipse()")}} {{experimental_inline}}</dt> + <dd>Adds an ellipse to the path which is centered at <em>(x, y)</em> position with the radii <em>radiusX</em> and <em>radiusY</em> starting at <em>startAngle</em> and ending at <em>endAngle</em> going in the given direction by <em>anticlockwise</em> (defaulting to clockwise).</dd> + <dt>{{domxref("CanvasRenderingContext2D.rect()")}}</dt> + <dd>Creates a path for a rectangle at<em> </em>position <em>(x, y)</em> with a size that is determined by <em>width</em> and <em>height</em>.</dd> +</dl> + +<h2 id="繪製路徑">繪製路徑</h2> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.fill()")}}</dt> + <dd>Fills the subpaths with the current fill style.</dd> + <dt>{{domxref("CanvasRenderingContext2D.stroke()")}}</dt> + <dd>Strokes the subpaths with the current stroke style.</dd> + <dt>{{domxref("CanvasRenderingContext2D.drawFocusIfNeeded()")}}</dt> + <dd>If a given element is focused, this method draws a focus ring around the current path.</dd> + <dt>{{domxref("CanvasRenderingContext2D.scrollPathIntoView()")}}</dt> + <dd>Scrolls the current path or a given path into the view.</dd> + <dt>{{domxref("CanvasRenderingContext2D.clip()")}}</dt> + <dd>Creates a clipping path from the current sub-paths. Everything drawn after <code>clip()</code> is called appears inside the clipping path only. For an example, see <a href="/en-US/docs/Web/API/Canvas_API/Tutorial/Compositing" title="Clipping paths">Clipping paths</a> in the Canvas tutorial.</dd> + <dt>{{domxref("CanvasRenderingContext2D.isPointInPath()")}}</dt> + <dd>Reports whether or not the specified point is contained in the current path.</dd> + <dt>{{domxref("CanvasRenderingContext2D.isPointInStroke()")}}</dt> + <dd>Reports whether or not the specified point is inside the area contained by the stroking of a path.</dd> +</dl> + +<h2 id="變形">變形</h2> + +<p>Objects in the <code>CanvasRenderingContext2D</code> rendering context have a current transformation matrix and methods to manipulate it. The transformation matrix is applied when creating the current default path, painting text, shapes and {{domxref("Path2D")}} objects. The methods listed below remain for historical and compatibility reasons as {{domxref("SVGMatrix")}} objects are used in most parts of the API nowadays and will be used in the future instead.</p> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.currentTransform")}}</dt> + <dd>Current transformation matrix ({{domxref("SVGMatrix")}} object).</dd> + <dt>{{domxref("CanvasRenderingContext2D.rotate()")}}</dt> + <dd>Adds a rotation to the transformation matrix. The angle argument represents a clockwise rotation angle and is expressed in radians.</dd> + <dt>{{domxref("CanvasRenderingContext2D.scale()")}}</dt> + <dd>Adds a scaling transformation to the canvas units by x horizontally and by y vertically.</dd> + <dt>{{domxref("CanvasRenderingContext2D.translate()")}}</dt> + <dd>Adds a translation transformation by moving the canvas and its origin x horzontally and y vertically on the grid.</dd> + <dt>{{domxref("CanvasRenderingContext2D.transform()")}}</dt> + <dd>Multiplies the current transformation matrix with the matrix described by its arguments.</dd> + <dt>{{domxref("CanvasRenderingContext2D.setTransform()")}}</dt> + <dd>Resets the current transform to the identity matrix, and then invokes the <code>transform()</code> method with the same arguments.</dd> + <dt>{{domxref("CanvasRenderingContext2D.resetTransform()")}} {{experimental_inline}}</dt> + <dd>Resets the current transform by the identity matrix.</dd> +</dl> + +<h2 id="合成">合成</h2> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.globalAlpha")}}</dt> + <dd>Alpha value that is applied to shapes and images before they are composited onto the canvas. Default <code>1.0</code> (opaque).</dd> + <dt>{{domxref("CanvasRenderingContext2D.globalCompositeOperation")}}</dt> + <dd>With <code>globalAlpha</code> applied this sets how shapes and images are drawn onto the existing bitmap.</dd> +</dl> + +<h2 id="繪製圖形">繪製圖形</h2> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.drawImage()")}}</dt> + <dd>Draws the specified image. This method is available in multiple formats, providing a great deal of flexibility in its use.</dd> +</dl> + +<h2 id="像素控制">像素控制</h2> + +<p>See also the {{domxref("ImageData")}} object.</p> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.createImageData()")}}</dt> + <dd>Creates a new, blank {{domxref("ImageData")}} object with the specified dimensions. All of the pixels in the new object are transparent black.</dd> + <dt>{{domxref("CanvasRenderingContext2D.getImageData()")}}</dt> + <dd>Returns an {{domxref("ImageData")}} object representing the underlying pixel data for the area of the canvas denoted by the rectangle which starts at <em>(sx, sy)</em> and has an <em>sw</em> width and <em>sh</em> height.</dd> + <dt>{{domxref("CanvasRenderingContext2D.putImageData()")}}</dt> + <dd>Paints data from the given {{domxref("ImageData")}} object onto the bitmap. If a dirty rectangle is provided, only the pixels from that rectangle are painted.</dd> +</dl> + +<h2 id="圖像平滑">圖像平滑</h2> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.imageSmoothingEnabled")}} {{experimental_inline}}</dt> + <dd>Image smoothing mode; if disabled, images will not be smoothed if scaled.</dd> +</dl> + +<h2 id="canvas_狀態">canvas 狀態</h2> + +<p>The <code>CanvasRenderingContext2D</code> rendering context contains a variety of drawing style states (attributes for line styles, fill styles, shadow styles, text styles). The following methods help you to work with that state:</p> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.save()")}}</dt> + <dd>Saves the current drawing style state using a stack so you can revert any change you make to it using <code>restore()</code>.</dd> + <dt>{{domxref("CanvasRenderingContext2D.restore()")}}</dt> + <dd>Restores the drawing style state to the last element on the 'state stack' saved by <code>save()</code>.</dd> + <dt>{{domxref("CanvasRenderingContext2D.canvas")}}</dt> + <dd>A read-only back-reference to the {{domxref("HTMLCanvasElement")}}. Might be {{jsxref("null")}} if it is not associated with a {{HTMLElement("canvas")}} element.</dd> +</dl> + +<h2 id="點擊區域">點擊區域</h2> + +<dl> + <dt>{{domxref("CanvasRenderingContext2D.addHitRegion()")}} {{experimental_inline}}</dt> + <dd>Adds a hit region to the canvas.</dd> + <dt>{{domxref("CanvasRenderingContext2D.removeHitRegion()")}} {{experimental_inline}}</dt> + <dd>Removes the hit region with the specified <code>id</code> from the canvas.</dd> + <dt>{{domxref("CanvasRenderingContext2D.clearHitRegions()")}} {{experimental_inline}}</dt> + <dd>Removes all hit regions from the canvas.</dd> +</dl> + +<h2 id="非標準_API">非標準 API</h2> + +<h3 id="Blink_及_WebKit_引擎">Blink 及 WebKit 引擎</h3> + +<p>Most of these APIs are <a href="https://code.google.com/p/chromium/issues/detail?id=363198">deprecated and will be removed in the future</a>.</p> + +<dl> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.clearShadow()</code></dt> + <dd>Removes all shadow settings like {{domxref("CanvasRenderingContext2D.shadowColor")}} and {{domxref("CanvasRenderingContext2D.shadowBlur")}}.</dd> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.drawImageFromRect()</code></dt> + <dd>This is redundant with an equivalent overload of <code>drawImage</code>.</dd> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.setAlpha()</code></dt> + <dd>Use {{domxref("CanvasRenderingContext2D.globalAlpha")}} instead.</dd> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.setCompositeOperation()</code></dt> + <dd>Use {{domxref("CanvasRenderingContext2D.globalCompositeOperation")}} instead.</dd> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.setLineWidth()</code></dt> + <dd>Use {{domxref("CanvasRenderingContext2D.lineWidth")}} instead.</dd> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.setLineJoin()</code></dt> + <dd>Use {{domxref("CanvasRenderingContext2D.lineJoin")}} instead.</dd> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.setLineCap()</code></dt> + <dd>Use {{domxref("CanvasRenderingContext2D.lineCap")}} instead.</dd> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.setMiterLimit()</code></dt> + <dd>Use {{domxref("CanvasRenderingContext2D.miterLimit")}} instead.</dd> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.setStrokeColor()</code></dt> + <dd>Use {{domxref("CanvasRenderingContext2D.strokeStyle")}} instead.</dd> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.setFillColor()</code></dt> + <dd>Use {{domxref("CanvasRenderingContext2D.fillStyle")}} instead.</dd> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.setShadow()</code></dt> + <dd>Use {{domxref("CanvasRenderingContext2D.shadowColor")}} and {{domxref("CanvasRenderingContext2D.shadowBlur")}} instead.</dd> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.webkitLineDash</code></dt> + <dd>Use {{domxref("CanvasRenderingContext2D.getLineDash()")}} and {{domxref("CanvasRenderingContext2D.setLineDash()")}} instead.</dd> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.webkitLineDashOffset</code></dt> + <dd>Use {{domxref("CanvasRenderingContext2D.lineDashOffset")}} instead.</dd> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.webkitImageSmoothingEnabled</code></dt> + <dd>Use {{domxref("CanvasRenderingContext2D.imageSmoothingEnabled")}} instead.</dd> +</dl> + +<h3 id="Blink_引擎專屬">Blink 引擎專屬</h3> + +<dl> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.getContextAttributes()</code></dt> + <dd>Inspired by the same <code>WebGLRenderingContext</code> method it returns an <code>Canvas2DContextAttributes</code> object that contains the attributes "storage" to indicate which storage is used ("persistent" by default) and the attribute "alpha" (<code>true</code> by default) to indicate that transparency is used in the canvas.</dd> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.isContextLost()</code></dt> + <dd>Inspired by the same <code>WebGLRenderingContext</code> method it returns <code>true</code> if the Canvas context has been lost, or <code>false</code> if not.</dd> +</dl> + +<h3 id="WebKit_引擎專屬">WebKit 引擎專屬</h3> + +<dl> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.webkitBackingStorePixelRatio</code></dt> + <dd>The backing store size in relation to the canvas element. See <a href="http://www.html5rocks.com/en/tutorials/canvas/hidpi/">High DPI Canvas</a>.</dd> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.webkitGetImageDataHD</code></dt> + <dd>Intended for HD backing stores, but removed from canvas specifications.</dd> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.webkitPutImageDataHD</code></dt> + <dd>Intended for HD backing stores, but removed from canvas specifications.</dd> +</dl> + +<dl> +</dl> + +<h3 id="Gecko_引擎專屬">Gecko 引擎專屬</h3> + +<dl> + <dt>{{non-standard_inline}} {{domxref("CanvasRenderingContext2D.filter")}}</dt> + <dd>CSS and SVG filters as Canvas APIs. Likely to be standardized in a new version of the specification.</dd> +</dl> + +<h4 id="Prefixed_APIs">Prefixed APIs</h4> + +<dl> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.mozCurrentTransform</code></dt> + <dd>Sets or gets the current transformation matrix, see {{domxref("CanvasRenderingContext2D.currentTransform")}}. {{ gecko_minversion_inline("7.0") }}</dd> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.mozCurrentTransformInverse</code></dt> + <dd>Sets or gets the current inversed transformation matrix. {{ gecko_minversion_inline("7.0") }}</dd> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.mozImageSmoothingEnabled</code></dt> + <dd>See {{domxref("CanvasRenderingContext2D.imageSmoothingEnabled")}}.</dd> + <dt>{{non-standard_inline}} {{deprecated_inline}} <code>CanvasRenderingContext2D.mozDash</code></dt> + <dd>An array which specifies the lengths of alternating dashes and gaps {{ gecko_minversion_inline("7.0") }}. Use {{domxref("CanvasRenderingContext2D.getLineDash()")}} and {{domxref("CanvasRenderingContext2D.setLineDash()")}} instead.</dd> + <dt>{{non-standard_inline}} {{deprecated_inline}} <code>CanvasRenderingContext2D.mozDashOffset</code></dt> + <dd>Specifies where to start a dash array on a line. {{ gecko_minversion_inline("7.0") }}. Use {{domxref("CanvasRenderingContext2D.lineDashOffset")}} instead.</dd> + <dt>{{non-standard_inline}} {{deprecated_inline}} <code>CanvasRenderingContext2D.mozTextStyle</code></dt> + <dd>Introduced in in Gecko 1.9, deprecated in favor of the {{domxref("CanvasRenderingContext2D.font")}} property.</dd> + <dt>{{non-standard_inline}} {{obsolete_inline}} <code>CanvasRenderingContext2D.mozDrawText()</code></dt> + <dd>This method was introduced in Gecko 1.9 and is removed starting with Gecko 7.0. Use {{domxref("CanvasRenderingContext2D.strokeText()")}} or {{domxref("CanvasRenderingContext2D.fillText()")}} instead.</dd> + <dt>{{non-standard_inline}} {{obsolete_inline}} <code>CanvasRenderingContext2D.mozMeasureText()</code></dt> + <dd>This method was introduced in Gecko 1.9 and is unimplemented starting with Gecko 7.0. Use {{domxref("CanvasRenderingContext2D.measureText()")}} instead.</dd> + <dt>{{non-standard_inline}} {{obsolete_inline}} <code>CanvasRenderingContext2D.mozPathText()</code></dt> + <dd>This method was introduced in Gecko 1.9 and is removed starting with Gecko 7.0.</dd> + <dt>{{non-standard_inline}} {{obsolete_inline}} <code>CanvasRenderingContext2D.mozTextAlongPath()</code></dt> + <dd>This method was introduced in Gecko 1.9 and is removed starting with Gecko 7.0.</dd> +</dl> + +<h4 id="Internal_APIs_(chrome-context_only)">Internal APIs (chrome-context only)</h4> + +<dl> + <dt>{{non-standard_inline}} {{domxref("CanvasRenderingContext2D.asyncDrawXULElement()")}}</dt> + <dd>Renders a region of a XUL element into the <code>canvas</code>.</dd> + <dt>{{non-standard_inline}} {{domxref("CanvasRenderingContext2D.drawWindow()")}}</dt> + <dd>Renders a region of a window into the <code>canvas</code>. The contents of the window's viewport are rendered, ignoring viewport clipping and scrolling.</dd> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.demote()</code></dt> + <dd>This causes a context that is currently using a hardware-accelerated backend to fallback to a software one. All state should be preserved.</dd> +</dl> + +<h3 id="Internet_Explorer">Internet Explorer</h3> + +<dl> + <dt>{{non-standard_inline}} <code>CanvasRenderingContext2D.msFillRule</code></dt> + <dd>The <a class="external" href="http://cairographics.org/manual/cairo-cairo-t.html#cairo-fill-rule-t" title="http://cairographics.org/manual/cairo-cairo-t.html#cairo-fill-rule-t">fill rule</a> to use. This must be one of <code>evenodd</code> or <code>nonzero</code> (default).</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('HTML WHATWG', "scripting.html#2dcontext:canvasrenderingcontext2d", "CanvasRenderingContext2D")}}</td> + <td>{{Spec2('HTML WHATWG')}}</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>Edge</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatChrome("1")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1.8")}}</td> + <td>{{CompatIE("9")}}</td> + <td>{{CompatOpera("9")}}</td> + <td>{{CompatSafari("2")}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="相容性註記">相容性註記</h2> + +<ul> + <li>Starting with Gecko 5.0 {{geckoRelease("5.0")}}, specifying invalid values are now silently ignored for the following methods and properties: <code>translate()</code>, <code>transform()</code>, <code>rotate(), </code><code>scale(),</code> <code>rect()</code>, <code>clearRect()</code>, <code>fillRect()</code>, <code>strokeRect()</code>, <code>lineTo()</code>, <code>moveTo()</code>, <code>quadraticCurveTo()</code>, <code>arc()</code>, <code>shadowOffsetX</code>, <code>shadowOffsetY</code>, <code>shadowBlur</code>.</li> +</ul> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("HTMLCanvasElement")}}</li> +</ul> + +<div class="s3gt_translate_tooltip" id="s3gt_translate_tooltip" style="position: absolute; left: 339px; top: 135px; opacity: 0.6;"> +<div class="s3gt_translate_tooltip_mini" id="s3gt_translate_tooltip_mini_logo" title="翻譯選取的文字"> </div> + +<div class="s3gt_translate_tooltip_mini" id="s3gt_translate_tooltip_mini_sound" title="朗讀"> </div> + +<div class="s3gt_translate_tooltip_mini" id="s3gt_translate_tooltip_mini_copy" title="將文字複製到剪貼簿"> </div> +</div> + +<div class="s3gt_translate_tooltip" id="s3gt_translate_tooltip" style="position: absolute; left: 126px; top: 158px;"> +<div class="s3gt_translate_tooltip_mini" id="s3gt_translate_tooltip_mini_logo" title="翻譯選取的文字"> </div> + +<div class="s3gt_translate_tooltip_mini" id="s3gt_translate_tooltip_mini_sound" title="朗讀"> </div> + +<div class="s3gt_translate_tooltip_mini" id="s3gt_translate_tooltip_mini_copy" title="將文字複製到剪貼簿"> </div> +</div> diff --git a/files/zh-tw/web/api/channel_messaging_api/index.html b/files/zh-tw/web/api/channel_messaging_api/index.html new file mode 100644 index 0000000000..1cf9d98692 --- /dev/null +++ b/files/zh-tw/web/api/channel_messaging_api/index.html @@ -0,0 +1,158 @@ +--- +title: Channel Messaging API +slug: Web/API/Channel_Messaging_API +translation_of: Web/API/Channel_Messaging_API +--- +<p>Channel Messaging API 讓同屬一份文件不同瀏覽環境的兩份程式腳本 (如兩個 IFrame、或主頁面和 IFrame、文件和 {{domxref("SharedWorker")}}、或兩個 worker)，也能夠經由雙向 channel (通道) 兩端的 port (連接阜) 直接傳遞訊息互相溝通。</p> + +<p>{{AvailableInWorkers}}</p> + +<h2 id="Channel_訊息概念與使用情境">Channel 訊息概念與使用情境</h2> + +<p>{{domxref("MessageChannel.MessageChannel", "MessageChannel()")}} 建構子產生 channel， 一但生成了，便可以存取 channel 兩端的 port: {{domxref("MessageChannel.port1")}} 和 {{domxref("MessageChannel.port2")}}，這兩個屬性會回傳 domxref("MessagePort")}} objects.)。建立 channel 的 app 使用 port1，另一端用 port2，利用 {{domxref("window.postMessage")}} 方法帶入參數，向 port2 傳送訊息以及移轉物件 (這裡也就是只 port)。</p> + +<p>一但可移轉物件被移轉後，前任擁有者便失去所有權，例如當 port 移轉出去後，原本持有該 port 的環境便不能再使用之。目前可移轉物件只有 {{domxref("ArrayBuffer")}} 以及 {{domxref("MessagePort")}}。</p> + +<p>另一端的瀏覽環境則藉由 {{domxref("MessagePort.onmessage")}} 監聽訊息、從訊息事件物件的 data 屬性擷取訊息資料，然後再呼叫 {{domxref("MessagePort.postMessage")}} 回傳訊息。</p> + +<p>如果想關閉訊息 channel，則呼叫 {{domxref("MessagePort.close")}}。</p> + +<p>更多 API 使用細節請見<a href="/en-US/docs/Web/API/Channel_Messaging_API/Using_channel_messaging"> Using channel messaging</a>。</p> + +<h2 id="Channel_訊息介面">Channel 訊息介面</h2> + +<dl> + <dt>{{domxref("MessageChannel")}}</dt> + <dd>生成一個新的 message channel。</dd> + <dt>{{domxref("MessagePort")}}</dt> + <dd>控制 port，用來傳送和監聽訊息。</dd> + <dt>{{domxref("PortCollection")}}</dt> + <dd><code>MessagePort</code>s 陣列，實驗性質方案；用來同時廣播到多個訊息 port。</dd> +</dl> + +<h2 id="範例">範例</h2> + +<ul> + <li>Github 上有<a href="https://github.com/mdn/channel-messaging-basic-demo"> channel messaging basic demo</a> (<a href="http://mdn.github.io/channel-messaging-basic-demo/">run it live too</a>)，一個簡單示範主頁和 {{htmlelement("iframe")}} 間的訊息溝通。</li> + <li>還有 <a href="https://github.com/mdn/channel-messaging-multimessage">multimessaging demo</a> (<a href="http://mdn.github.io/channel-messaging-multimessage/">run this live</a>)，較為複雜的例子。</li> +</ul> + +<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('HTML WHATWG', '#toc-comms')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>Channel messaging defined in section 9.5. No difference to the the HTML5 Web Messaging spec.</td> + </tr> + <tr> + <td>{{SpecName('HTML5 Web Messaging', '#channel-messaging')}}</td> + <td>{{Spec2('HTML5 Web Messaging')}}</td> + <td>W3C version of the 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>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>4</td> + <td>{{CompatGeckoDesktop(41)}}</td> + <td>10.0</td> + <td>10.6</td> + <td>5</td> + </tr> + <tr> + <td>PortCollection</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>Available in workers</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(41)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome Mobile</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>4.4</td> + <td>4</td> + <td>{{CompatGeckoMobile(41)}}</td> + <td>{{CompatNo}}</td> + <td>10.0</td> + <td>11.5</td> + <td>5.1</td> + </tr> + <tr> + <td>PortCollection</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>Available in workers</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile(41)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="延伸閱讀">延伸閱讀</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/Channel_Messaging_API/Using_channel_messaging">Using channel messaging</a></li> + <li><a href="/en-US/docs/Web/API/Web_Workers_API">Web Workers API</a></li> + <li><a href="/en-US/docs/Web/API/Broadcast_Channel_API">Broadcast Channel API</a></li> +</ul> diff --git a/files/zh-tw/web/api/characterdata/index.html b/files/zh-tw/web/api/characterdata/index.html new file mode 100644 index 0000000000..5e39a14822 --- /dev/null +++ b/files/zh-tw/web/api/characterdata/index.html @@ -0,0 +1,156 @@ +--- +title: CharacterData +slug: Web/API/CharacterData +translation_of: Web/API/CharacterData +--- +<p>{{APIRef("DOM")}}</p> + +<p><code><strong>CharacterData</strong></code> 介面表示了含有字元的 {{domxref("Node")}} 物件。<code>CharacterData</code> 為抽象介面，代表不會有型別為 <code>CharacterData</code> 的物件。物件是由其子介面，如 {{domxref("Text")}}、{{domxref("Comment")}} 或 {{domxref("ProcessingInstruction")}} 等非抽象介面來實作。</p> + +<p>{{InheritanceDiagram}}</p> + +<h2 id="屬性">屬性</h2> + +<p><em>Inherits properties from its parent, {{domxref("Node")}}, and implements the {{domxref("ChildNode")}} and {{domxref("NonDocumentTypeChildNode")}} interface.</em></p> + +<dl> + <dt>{{domxref("CharacterData.data")}}</dt> + <dd>Is a {{domxref("DOMString")}} representing the textual data contained in this object.</dd> + <dt>{{domxref("CharacterData.length")}} {{readonlyInline}}</dt> + <dd>Returns an <code>unsigned long</code> representing the size of the string contained in <code>CharacterData.data</code>.</dd> + <dt>{{domxref("NonDocumentTypeChildNode.nextElementSibling")}} {{readonlyInline}}</dt> + <dd>Returns the {{domxref("Element")}} immediately following the specified one in its parent's children list, or <code>null</code> if the specified element is the last one in the list.</dd> + <dt>{{domxref("NonDocumentTypeChildNode.previousElementSibling")}} {{readonlyInline}}</dt> + <dd>Returns the {{domxref("Element")}} immediately prior to the specified one in its parent's children list, or <code>null</code> if the specified element is the first one in the list.</dd> +</dl> + +<h2 id="Methods" name="Methods">方法</h2> + +<p><em>Inherits methods from its parent, {{domxref("Node")}}, and implements the {{domxref("ChildNode")}} <em>and {{domxref("NonDocumentTypeChildNode")}} </em>interface.</em></p> + +<dl> + <dt>{{domxref("CharacterData.appendData()")}}</dt> + <dd>Appends the given {{domxref("DOMString")}} to the <code>CharacterData.data</code> string; when this method returns, <code>data</code> contains the concatenated {{domxref("DOMString")}}.</dd> + <dt>{{domxref("CharacterData.deleteData()")}}</dt> + <dd>Removes the specified amount of characters, starting at the specified offset, from the <code>CharacterData.data</code> string; when this method returns, <code>data</code> contains the shortened {{domxref("DOMString")}}.</dd> + <dt>{{domxref("CharacterData.insertData()")}}</dt> + <dd>Inserts the specified characters, at the specified offset, in the <code>CharacterData.data</code> string; when this method returns, <code>data</code> contains the modified {{domxref("DOMString")}}.</dd> + <dt>{{domxref("ChildNode.remove()")}} {{experimental_inline}}</dt> + <dd>Removes the object from its parent children list.</dd> + <dt>{{domxref("CharacterData.replaceData()")}}</dt> + <dd>Replaces the specified amount of characters, starting at the specified offset, with the specified {{domxref("DOMString")}}; when this method returns, <code>data</code> contains the modified {{domxref("DOMString")}}.</dd> + <dt>{{domxref("CharacterData.substringData()")}}</dt> + <dd>Returns a {{domxref("DOMString")}} containing the part of <code>CharacterData.data</code> of the specified length and starting at the specified offset.</dd> +</dl> + +<h2 id="Specification" name="Specification">規範</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('DOM WHATWG', '#characterdata', 'CharacterData')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>Added implemention of the {{domxref("ChildNode")}} and {{domxref("NonDocumentTypeChildNode")}} interface.</td> + </tr> + <tr> + <td>{{SpecName('DOM3 Core', 'core.html#ID-FF21A306', 'CharacterData')}}</td> + <td>{{Spec2('DOM3 Core')}}</td> + <td>No change from {{SpecName('DOM2 Core')}}.</td> + </tr> + <tr> + <td>{{SpecName('DOM2 Core', 'core.html#ID-FF21A306', 'CharacterData')}}</td> + <td>{{Spec2('DOM2 Core')}}</td> + <td>No change from {{SpecName('DOM1')}}.</td> + </tr> + <tr> + <td>{{SpecName('DOM1', 'level-one-core.html#ID-FF21A306', 'CharacterData')}}</td> + <td>{{Spec2('DOM1')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>1.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1.0")}}</td> + <td>6</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>Implements {{domxref("ChildNode")}} interface.</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("25.0")}} [1]</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</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>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("1.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>Implements {{domxref("ChildNode")}} interface.</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("25.0")}} [1]</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Two properties, <code>nextElementSibling</code> and <code>previousElementSibling</code>, have been moved to the {{domxref("NonDocumentTypeChildNode")}} interface, also implemented by <code>CharacterData</code>.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/zh-TW/docs/DOM/DOM_Reference" title="/en-US/docs/DOM/DOM_Reference">The DOM interfaces index</a>.</li> +</ul> diff --git a/files/zh-tw/web/api/childnode/index.html b/files/zh-tw/web/api/childnode/index.html new file mode 100644 index 0000000000..1d7d3f753b --- /dev/null +++ b/files/zh-tw/web/api/childnode/index.html @@ -0,0 +1,182 @@ +--- +title: ChildNode +slug: Web/API/ChildNode +translation_of: Web/API/ChildNode +--- +<div>{{APIRef("DOM")}}</div> + +<p><code><strong>childNodes</strong></code> 介面定義了可以擁有父節點之 {{domxref("Node")}} 物件的方法。</p> + +<p><code>childNodes</code> 是一個原始的介面，且不能以此建立物件實體。{{domxref("Element")}}、{{domxref("DocumentType")}} 及 {{domxref("CharacterData")}} 物件皆實作了 <code>childNodes</code>。</p> + +<h2 id="屬性">屬性</h2> + +<p><em>沒有繼承或自有的屬性。</em></p> + +<h2 id="方法">方法</h2> + +<p><em>沒有繼承的方法。</em></p> + +<dl> + <dt>{{domxref("childNodes.remove()")}} {{experimental_inline}}</dt> + <dd>Removes this <code>childNodes</code> from the children list of its parent.</dd> + <dt>{{domxref("childNodes.before()")}} {{experimental_inline}}</dt> + <dd>Inserts a set of {{domxref("Node")}} or {{domxref("DOMString")}} objects in the children list of this <code>childNodes</code>'s parent, just before this <code>childNodes</code>. {{domxref("DOMString")}} objects are inserted as equivalent {{domxref("Text")}} nodes.</dd> + <dt>{{domxref("childNodes.after()")}} {{experimental_inline}}</dt> + <dd>Inserts a set of {{domxref("Node")}} or {{domxref("DOMString")}} objects in the children list of this <code>childNodes</code>'s parent, just after this <code>childNodes</code>. {{domxref("DOMString")}} objects are inserted as equivalent {{domxref("Text")}} nodes.</dd> + <dt>{{domxref("childNodes.replaceWith()")}} {{experimental_inline}}</dt> + <dd>Replaces this <code>childNodes</code> in the children list of its parent with a set of {{domxref("Node")}} or {{domxref("DOMString")}} objects. {{domxref("DOMString")}} objects are inserted as equivalent {{domxref("Text")}} nodes.</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('DOM WHATWG', '#interface-childnode', 'childNodes')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>Split the <code>ElementTraversal</code> interface in {{domxref("ParentNode")}} and <code>childNodes</code>. <code>previousElementSibling</code> and <code>nextElementSibling</code> are now defined on the latter. The {{domxref("CharacterData")}} and {{domxref("DocumentType")}} implemented the new interfaces. Added the <code>remove()</code>, <code>before()</code>, <code>after()</code> and <code>replaceWith()</code> methods.</td> + </tr> + <tr> + <td>{{SpecName('Element Traversal', '#interface-elementTraversal', 'ElementTraversal')}}</td> + <td>{{Spec2('Element Traversal')}}</td> + <td>Added the initial definition of its properties to the <code>ElementTraversal</code> pure interface and use it on {{domxref("Element")}}.</td> + </tr> + </tbody> +</table> + +<h2 id="Polyfill">Polyfill</h2> + +<p>External on github: <a href="https://github.com/seznam/JAK/blob/master/lib/polyfills/childNode.js">childNode.js</a></p> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{ CompatibilityTable }}</p> + +<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 (on {{domxref("Element")}})</td> + <td>{{CompatChrome(1.0)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(23)}}</td> + <td>9.0</td> + <td>10.0</td> + <td>4.0</td> + </tr> + <tr> + <td>Support on {{domxref("DocumentType")}} and {{domxref("CharacterData")}} {{experimental_inline}}</td> + <td>{{CompatChrome(23.0)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop(23)}}</td> + <td>{{CompatNo}}</td> + <td>16.0</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>remove()</code>{{experimental_inline}}</td> + <td>{{CompatChrome(29.0)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(23)}}</td> + <td>{{CompatNo}}</td> + <td>16.0</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>before()</code>, <code>after()</code>, and <code>replaceWith()</code> {{experimental_inline}}</td> + <td>{{CompatChrome(54.0)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop(49)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatOpera(39)}}</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>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + <th>Chrome for Android</th> + </tr> + <tr> + <td>Basic support (on {{domxref("Element")}})</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile(23)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>10.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>Support on {{domxref("DocumentType")}} and {{domxref("CharacterData")}} {{experimental_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile(23)}}</td> + <td>{{CompatNo}}</td> + <td>16.0</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>remove()</code>{{experimental_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile(23)}}</td> + <td>{{CompatNo}}</td> + <td>16.0</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>before()</code>, <code>after()</code>, and <code>replaceWith()</code> {{experimental_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatChrome(54.0)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile(49)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatOperaMobile(39)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatChrome(54.0)}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li>The {{domxref("ParentNode")}} pure interface.</li> + <li> + <div class="syntaxbox">Object types implementing this pure interface: {{domxref("CharacterData")}}, {{domxref("Element")}}, and {{domxref("DocumentType")}}.</div> + </li> +</ul> diff --git a/files/zh-tw/web/api/clients/index.html b/files/zh-tw/web/api/clients/index.html new file mode 100644 index 0000000000..000e36a804 --- /dev/null +++ b/files/zh-tw/web/api/clients/index.html @@ -0,0 +1,113 @@ +--- +title: Clients +slug: Web/API/Clients +translation_of: Web/API/Clients +--- +<p>{{SeeCompatTable}}{{APIRef("Service Workers API")}}</p> + +<p>The <code>Clients</code> interface of the <a href="/en-US/docs/Web/API/Service_Worker_API">Service Workers API</a> represents a container for a list of {{domxref("Client")}} objects.</p> + +<h2 id="Methods">Methods</h2> + +<dl> + <dt>{{domxref("Clients.get()")}}</dt> + <dd>Gets a service worker client matching a given <code>id</code> and returns it in a {{jsxref("Promise")}}.</dd> + <dt>{{domxref("Clients.matchAll()")}}</dt> + <dd>Gets a list of service worker clients and returns them in a {{jsxref("Promise")}}. Include the <code>options</code> parameter to return all service worker clients whose origin is the same as the associated service worker's origin. If <code>options</code> are not included, the method returns only the service worker clients controlled by the service worker. </dd> + <dt>{{domxref("Clients.openWindow()")}}</dt> + <dd>Opens a service worker {{domxref("Client")}} in a new browser window.</dd> + <dt>{{domxref("Clients.claim()")}}</dt> + <dd>Allows an active Service Worker to set itself as the active worker for a client page when the worker and the page are in the same scope. </dd> +</dl> + +<h2 id="Examples">Examples</h2> + +<pre class="brush: js">clients.matchAll(options).then(function(clients) { + for(i = 0 ; i < clients.length ; i++) { + if(clients[i] === 'index.html') { + clients.openWindow(clients[i]); + // or do something else involving the matching client + } + } +});</pre> + +<h2 id="Specifications">Specifications</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('Service Workers', '#clients', 'Clients')}}</td> + <td>{{Spec2('Service Workers')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatChrome(40.0)}}</td> + <td>{{ CompatGeckoDesktop("44.0") }}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</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>Firefox Mobile (Gecko)</th> + <th>Firefox OS</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>{{CompatUnknown}}</td> + <td>{{ CompatGeckoMobile("44.0") }}</td> + <td>{{ CompatVersionUnknown }}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/ServiceWorker_API/Using_Service_Workers">Using Service Workers</a></li> + <li><a href="https://github.com/mdn/sw-test">Service workers basic code example</a></li> + <li><a href="https://jakearchibald.github.io/isserviceworkerready/">Is ServiceWorker ready?</a></li> + <li>{{jsxref("Promise")}}</li> + <li><a href="/en-US/docs/Web/Guide/Performance/Using_web_workers">Using web workers</a></li> +</ul> diff --git a/files/zh-tw/web/api/clipboardevent/index.html b/files/zh-tw/web/api/clipboardevent/index.html new file mode 100644 index 0000000000..7353cf4978 --- /dev/null +++ b/files/zh-tw/web/api/clipboardevent/index.html @@ -0,0 +1,119 @@ +--- +title: ClipboardEvent +slug: Web/API/ClipboardEvent +translation_of: Web/API/ClipboardEvent +--- +<p>{{APIRef("Clipboard API")}} {{SeeCompatTable}}</p> + +<p><strong><code>ClipboardEvent</code></strong> 介面表示了與修改剪貼簿相關的事件，包括 {{event("cut")}}、{{event("copy")}} 及 {{event("paste")}} 事件。</p> + +<h2 id="屬性">屬性</h2> + +<p><em>Also inherits properties from its parent {{domxref("Event")}}</em>.</p> + +<dl> + <dt>{{domxref("ClipboardEvent.clipboardData")}} {{readonlyInline}}</dt> + <dd>Is a {{domxref("DataTransfer")}} object containing the data affected by the user-initiated {{event("cut")}}, {{event("copy")}}, or {{event("paste")}} operation, along with its MIME type.</dd> +</dl> + +<h2 id="建構式">建構式</h2> + +<dl> + <dt>{{domxref("ClipboardEvent.ClipboardEvent", "ClipboardEvent()")}}</dt> + <dd>Creates a <code>ClipboardEvent</code> event with the given parameters.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>No specific methods; inherits methods from its parent {{domxref("Event")}}</em>.</p> + +<h2 id="規範">規範</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('Clipboard API', '#clipboard-event-interfaces', 'ClipboardEvent') }}</td> + <td>{{ Spec2('Clipboard API') }}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>4.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>clipboardData</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("22.0")}}</td> + <td>5.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>4.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>clipboardData</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("22.0")}}</td> + <td>5.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li>Copy-related events: {{event("copy")}}, {{event("cut")}}, {{event("paste")}}</li> +</ul> diff --git a/files/zh-tw/web/api/console/assert/index.html b/files/zh-tw/web/api/console/assert/index.html new file mode 100644 index 0000000000..415b4cfa9a --- /dev/null +++ b/files/zh-tw/web/api/console/assert/index.html @@ -0,0 +1,118 @@ +--- +title: Console.assert() +slug: Web/API/console/assert +tags: + - API + - DOM + - Debugging + - 函式 + - 控制台 + - 網頁控制台 + - 網頁開發 +translation_of: Web/API/console/assert +--- +<div>{{APIRef("Console API")}}</div> + +<p>如果斷言（assertion）為非（false），主控台會顯示錯誤訊息；如果斷言為是（true），則不發生任何事。</p> + +<p>{{AvailableInWorkers}}</p> + +<div class="note"> +<p><strong>注意</strong>：<em>在 Node.js 內 <code>console.assert()</code> 方法的實做，與瀏覽器並不相同。</em></p> + +<p>瀏覽器內呼叫 falsy 的 <code>console.assert()</code> 斷言出現 <code>message</code>，但不會中斷程式碼的執行。然而在 Node.js 裡面，falsy 斷言會拋出 <code>AssertionError</code> 錯誤。</p> +</div> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">console.assert(<em>assertion</em>, <em>obj1</em> [, <em>obj2</em>, ..., <em>objN</em>]); +console.assert(<em>assertion</em>, <em>msg</em> [, <em>subst1</em>, ..., <em>substN</em>]); // c-like message formatting +</pre> + +<h3 id="參數">參數</h3> + +<dl> + <dt><code>assertion</code></dt> + <dd>布林表達式。如果斷言為非，訊息會出現在主控台上。</dd> + <dt><code>obj1</code> ... <code>objN</code></dt> + <dd>要印出來的 JavaScript 物件名單。 The string representations of each of these objects are appended together in the order listed and output.</dd> + <dt><code>msg</code></dt> + <dd>包含零個以上的 JavaScript 替代（substitution）字串。</dd> + <dt><code>subst1</code> ... <code>substN</code></dt> + <dd>JavaScript objects with which to replace substitution strings within <code>msg</code>. This parameter gives you additional control over the format of the output.</dd> +</dl> + +<p>請參見 {{domxref("console")}} 的 <a href="/zh-TW/docs/Web/API/console#Outputting_text_to_the_console">Outputting text to the console</a> 以獲取詳細資訊。</p> + +<h2 id="範例">範例</h2> + +<p>以下程式碼示範一個 JavaScript 物件的斷言使用：</p> + +<pre class="brush: js">const errorMsg = 'the # is not even'; +for (let number = 2; number <= 5; number += 1) { + console.log('the # is ' + number); + console.assert(number % 2 === 0, {number: number, errorMsg: errorMsg}); + // or, using ES2015 object property shorthand: + // console.assert(number % 2 === 0, {number, errorMsg}); +} +// output: +// the # is 2 +// the # is 3 +// Assertion failed: {number: 3, errorMsg: "the # is not even"} +// the # is 4 +// the # is 5 +// Assertion failed: {number: 5, errorMsg: "the # is not even"} +</pre> + +<p>請注意，雖然包含替換字符串的字符串在 Node 中用作 <code>console.log</code> 的參數，但很多（如果不是大多數）瀏覽器...</p> + +<pre class="brush: js">console.log('the word is %s', 'foo'); +// output: the word is foo +</pre> + +<p>...在所有瀏覽器中，使用此類字符串目前無法作為console.assert的參數使用：</p> + +<pre class="brush: js">console.assert(false, 'the word is %s', 'foo'); +// correct output in Node (e.g. v8.10.0) and some browsers +// (e.g. Firefox v60.0.2): +// Assertion failed: the word is foo +// incorrect output in some browsers +// (e.g. Chrome v67.0.3396.87): +// Assertion failed: the word is %s foo +</pre> + +<p>有關詳細信息，請參閱 {{domxref("console")}} 文檔中的<a href="https://developer.mozilla.org/zh-TW/docs/Web/API/console#Outputting_text_to_the_console">將文本輸出到控制台</a>。</p> + +<h2 id="規範">規範</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("Console API", "#assert", "console.assert()")}}</td> + <td>{{Spec2("Console API")}}</td> + <td>初始定義</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + + + +<p>{{Compat("api.Console.assert")}}</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="https://console.spec.whatwg.org/#assert-condition-data">WHATWG Console Standard: console.assert</a></li> + <li><a href="http://www.opera.com/dragonfly/documentation/console/">Opera Dragonfly documentation: Console</a></li> + <li><a href="http://msdn.microsoft.com/library/gg589530">MSDN: Using the F12 Tools Console to View Errors and Status</a></li> + <li><a href="https://developer.chrome.com/devtools/docs/console#assertions">Chrome Developer Tools: Using the Console</a></li> +</ul> diff --git a/files/zh-tw/web/api/console/index.html b/files/zh-tw/web/api/console/index.html new file mode 100644 index 0000000000..36320a69a8 --- /dev/null +++ b/files/zh-tw/web/api/console/index.html @@ -0,0 +1,289 @@ +--- +title: Console +slug: Web/API/Console +tags: + - API + - Debugging + - Interface + - NeedsCompatTable + - NeedsTranslation + - Reference + - TopicStub + - console + - web console +translation_of: Web/API/Console +--- +<div>{{APIRef("Console API")}}</div> + +<p>The <strong><code>Console</code></strong> object provides access to the browser's debugging console (e.g. the <a href="/en-US/docs/Tools/Web_Console">Web Console</a> in Firefox). The specifics of how it works varies from browser to browser, but there is a <em>de facto</em> set of features that are typically provided.</p> + +<p>The <code>Console</code> object can be accessed from any global object. {{domxref("Window")}} on browsing scopes and {{domxref("WorkerGlobalScope")}} as specific variants in workers via the property console. It's exposed as {{domxref("Window.console")}}, and can be referenced as simply <code>console</code>. For example:</p> + +<pre class="brush: js">console.log("Failed to open the specified link")</pre> + +<p>This page documents the {{anch("Methods")}} available on the <code>Console</code> object and gives a few {{anch("Usage")}} examples.</p> + +<p>{{AvailableInWorkers}}</p> + +<h2 id="Methods">Methods</h2> + +<dl> + <dt>{{domxref("Console.assert()")}}</dt> + <dd>Log a message and stack trace to console if the first argument is <code>false</code>.</dd> + <dt>{{domxref("Console.clear()")}}</dt> + <dd>Clear the console.</dd> + <dt>{{domxref("Console.count()")}}</dt> + <dd>Log the number of times this line has been called with the given label.</dd> + <dt>{{domxref("Console.debug()")}}</dt> + <dd>An alias for <code>log()</code>. + <div class="note"><strong>Note</strong>: Starting with Chromium 58 this method only appears in Chromium browser consoles when level "Verbose" is selected.</div> + </dd> + <dt>{{domxref("Console.dir()")}} {{Non-standard_inline}}</dt> + <dd>Displays an interactive listing of the properties of a specified JavaScript object. This listing lets you use disclosure triangles to examine the contents of child objects.</dd> + <dt>{{domxref("Console.dirxml()")}} {{Non-standard_inline}}</dt> + <dd> + <p>Displays an XML/HTML Element representation of the specified object if possible or the JavaScript Object view if it is not possible.</p> + </dd> + <dt>{{domxref("Console.error()")}}</dt> + <dd>Outputs an error message. You may use <a href="/en-US/docs/Web/API/console#Using_string_substitutions">string substitution</a> and additional arguments with this method.</dd> + <dt>{{domxref("Console.exception()")}} {{Non-standard_inline}} {{deprecated_inline}}</dt> + <dd>An alias for <code>error()</code>.</dd> + <dt>{{domxref("Console.group()")}}</dt> + <dd>Creates a new inline <a href="/en-US/docs/Web/API/console#Using_groups_in_the_console">group</a>, indenting all following output by another level. To move back out a level, call <code>groupEnd()</code>.</dd> + <dt>{{domxref("Console.groupCollapsed()")}}</dt> + <dd>Creates a new inline <a href="/en-US/docs/Web/API/console#Using_groups_in_the_console">group</a>, indenting all following output by another level. However, unlike <code>group()</code> this starts with the inline group collapsed requiring the use of a disclosure button to expand it. To move back out a level, call <code>groupEnd()</code>.</dd> + <dt>{{domxref("Console.groupEnd()")}}</dt> + <dd>Exits the current inline <a href="/en-US/docs/Web/API/console#Using_groups_in_the_console">group</a>.</dd> + <dt>{{domxref("Console.info()")}}</dt> + <dd>Informative logging of information. You may use <a href="/en-US/docs/Web/API/console#Using_string_substitutions">string substitution</a> and additional arguments with this method.</dd> + <dt>{{domxref("Console.log()")}}</dt> + <dd>For general output of logging information. You may use <a href="/en-US/docs/Web/API/console#Using_string_substitutions">string substitution</a> and additional arguments with this method.</dd> + <dt>{{domxref("Console.profile()")}} {{Non-standard_inline}}</dt> + <dd>Starts the browser's built-in profiler (for example, the <a href="/en-US/docs/Tools/Performance">Firefox performance tool</a>). You can specify an optional name for the profile.</dd> + <dt>{{domxref("Console.profileEnd()")}} {{Non-standard_inline}}</dt> + <dd>Stops the profiler. You can see the resulting profile in the browser's performance tool (for example, the <a href="/en-US/docs/Tools/Performance">Firefox performance tool</a>).</dd> + <dt>{{domxref("Console.table()")}}</dt> + <dd>Displays tabular data as a table.</dd> + <dt>{{domxref("Console.time()")}}</dt> + <dd>Starts a <a href="/en-US/docs/Web/API/console#Timers">timer</a> with a name specified as an input parameter. Up to 10,000 simultaneous timers can run on a given page.</dd> + <dt>{{domxref("Console.timeEnd()")}}</dt> + <dd>Stops the specified <a href="/en-US/docs/Web/API/console#Timers">timer</a> and logs the elapsed time in seconds since it started.</dd> + <dt>{{domxref("Console.timeStamp()")}} {{Non-standard_inline}}</dt> + <dd>Adds a marker to the browser's <a href="https://developer.chrome.com/devtools/docs/timeline">Timeline</a> or <a href="/en-US/docs/Tools/Performance/Waterfall">Waterfall</a> tool.</dd> + <dt>{{domxref("Console.trace()")}}</dt> + <dd>Outputs a <a href="/en-US/docs/Web/API/console#Stack_traces">stack trace</a>.</dd> + <dt>{{domxref("Console.warn()")}}</dt> + <dd>Outputs a warning message. You may use <a href="/en-US/docs/Web/API/console#Using_string_substitutions">string substitution</a> and additional arguments with this method.</dd> +</dl> + +<h2 id="Usage" name="Usage">Usage</h2> + +<h3 id="Outputting_text_to_the_console" name="Outputting_text_to_the_console">Outputting text to the console</h3> + +<p>The most frequently-used feature of the console is logging of text and other data. There are four categories of output you can generate, using the {{domxref("console.log()")}}, {{domxref("console.info()")}}, {{domxref("console.warn()")}}, and {{domxref("console.error()")}} methods respectively. Each of these results in output styled differently in the log, and you can use the filtering controls provided by your browser to only view the kinds of output that interest you.</p> + +<p>There are two ways to use each of the output methods; you can simply pass in a list of objects whose string representations get concatenated into one string, then output to the console, or you can pass in a string containing zero or more substitution strings followed by a list of objects to replace them.</p> + +<h4 id="Outputting_a_single_object">Outputting a single object</h4> + +<p>The simplest way to use the logging methods is to output a single object:</p> + +<pre class="brush: js">var someObject = { str: "Some text", id: 5 }; +console.log(someObject); +</pre> + +<p>The output looks something like this:</p> + +<pre>[09:27:13.475] ({str:"Some text", id:5})</pre> + +<h4 id="Outputting_multiple_objects">Outputting multiple objects</h4> + +<p>You can also output multiple objects by simply listing them when calling the logging method, like this:</p> + +<pre class="brush: js">var car = "Dodge Charger"; +var someObject = { str: "Some text", id: 5 }; +console.info("My first car was a", car, ". The object is:", someObject);</pre> + +<p>This output will look like this:</p> + +<pre>[09:28:22.711] My first car was a Dodge Charger . The object is: ({str:"Some text", id:5}) +</pre> + +<h4 id="Using_string_substitutions">Using string substitutions</h4> + +<p>Gecko 9.0 {{geckoRelease("9.0")}} introduced support for string substitutions. When passing a string to one of the console object's methods that accepts a string, you may use these substitution strings:</p> + +<table class="standard-table" style="width: auto;"> + <tbody> + <tr> + <td class="header">Substitution string</td> + <td class="header">Description</td> + </tr> + <tr> + <td>%o or %O</td> + <td>Outputs a JavaScript object. Clicking the object name opens more information about it in the inspector.</td> + </tr> + <tr> + <td>%d or %i</td> + <td>Outputs an integer. Number formatting is supported, for example <code>console.log("Foo %.2d", 1.1)</code> will output the number as two significant figures with a leading 0: <code>Foo 01</code></td> + </tr> + <tr> + <td>%s</td> + <td>Outputs a string.</td> + </tr> + <tr> + <td>%f</td> + <td>Outputs a floating-point value. Formatting is supported, for example <code>console.log("Foo %.2f", 1.1)</code> will output the number to 2 decimal places: <code>Foo 1.10</code></td> + </tr> + </tbody> +</table> + +<div class="note"> +<p><strong>Note</strong>: Precision formatting doesn't work in Chrome</p> +</div> + +<p>Each of these pulls the next argument after the format string off the parameter list. For example:</p> + +<pre>for (var i=0; i<5; i++) { + console.log("Hello, %s. You've called me %d times.", "Bob", i+1); +} +</pre> + +<p>The output looks like this:</p> + +<pre>[13:14:13.481] Hello, Bob. You've called me 1 times. +[13:14:13.483] Hello, Bob. You've called me 2 times. +[13:14:13.485] Hello, Bob. You've called me 3 times. +[13:14:13.487] Hello, Bob. You've called me 4 times. +[13:14:13.488] Hello, Bob. You've called me 5 times. +</pre> + +<h4 id="Styling_console_output">Styling console output</h4> + +<p>You can use the <code>%c</code> directive to apply a CSS style to console output:</p> + +<pre class="brush: js">console.log("This is %cMy stylish message", "color: yellow; font-style: italic; background-color: blue;padding: 2px");</pre> + +<div>The text before the directive will not be affected, but the text after the directive will be styled using the CSS declarations in the parameter.</div> + +<div> </div> + +<div><img alt="" src="https://mdn.mozillademos.org/files/12527/CSS-styling.png" style="display: block; margin: 0 auto;"></div> + +<div> </div> + +<div class="note"> +<p><strong>Note</strong>: Quite a few CSS properties are supported by this styling; you should experiment and see which ones prove useful.</p> +</div> + +<div> </div> + +<div>{{h3_gecko_minversion("Using groups in the console", "9.0")}}</div> + +<p>You can use nested groups to help organize your output by visually combining related material. To create a new nested block, call <code>console.group()</code>. The <code>console.groupCollapsed()</code> method is similar but creates the new block collapsed, requiring the use of a disclosure button to open it for reading.</p> + +<div class="note"><strong>Note:</strong> Collapsed groups are not supported yet in Gecko; the <code>groupCollapsed()</code> method is the same as <code>group()</code> at this time.</div> + +<p>To exit the current group, simply call <code>console.groupEnd()</code>. For example, given this code:</p> + +<pre class="brush: js">console.log("This is the outer level"); +console.group(); +console.log("Level 2"); +console.group(); +console.log("Level 3"); +console.warn("More of level 3"); +console.groupEnd(); +console.log("Back to level 2"); +console.groupEnd(); +console.debug("Back to the outer level"); +</pre> + +<p>The output looks like this:</p> + +<p><img alt="nesting.png" class="default internal" src="/@api/deki/files/6082/=nesting.png"></p> + +<div>{{h3_gecko_minversion("Timers", "10.0")}}</div> + +<p>In order to calculate the duration of a specific operation, Gecko 10 introduced the support of timers in the <code>console</code> object. To start a timer, call the <code>console.time</code><code>()</code> method, giving it a name as the only parameter. To stop the timer, and to get the elapsed time in milliseconds, just call the <code>console.timeEnd()</code> method, again passing the timer's name as the parameter. Up to 10,000 timers can run simultaneously on a given page.</p> + +<p>For example, given this code:</p> + +<pre class="brush: js">console.time("answer time"); +alert("Click to continue"); +console.timeEnd("answer time"); +</pre> + +<p>Will log the time needed by the user to discard the alert box:</p> + +<p><img alt="timerresult.png" class="default internal" src="/@api/deki/files/6084/=timerresult.png"></p> + +<p>Notice that the timer's name is displayed both when the timer is started and when it's stopped.</p> + +<div class="note"><strong>Note:</strong> It's important to note that if you're using this to log the timing for network traffic, the timer will report the total time for the transaction, while the time listed in the network panel is just the amount of time required for the header. If you have response body logging enabled, the time listed for the response header and body combined should match what you see in the console output.</div> + +<h3 id="Stack_traces">Stack traces</h3> + +<p>The console object also supports outputting a stack trace; this will show you the call path taken to reach the point at which you call {{domxref("console.trace()")}}. Given code like this:</p> + +<pre class="brush: js">function foo() { + function bar() { + console.trace(); + } + bar(); +} + +foo(); +</pre> + +<p>The output in the console looks something like this:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/7167/api-trace2.png" style="display: block; margin-left: auto; margin-right: auto;"></p> + +<h2 id="Specifications">Specifications</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('Console API')}}</td> + <td>{{Spec2('Console API')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + + + +<p>{{Compat("api.Console")}}</p> + +<h2 id="Notes">Notes</h2> + +<ul> + <li>At least in Firefox, if a page defines a <code>console</code> object, that object overrides the one built into Firefox.</li> + <li>Prior to {{Gecko("12.0")}}, the console object's methods only work when the Web Console is open. Starting with {{Gecko("12.0")}}, output is cached until the Web Console is opened, then displayed at that time.</li> + <li>It's worth noting that the Firefox's built-in <code>Console</code> object is compatible with the one provided by <a class="external" href="http://getfirebug.com/" title="http://getfirebug.com/">Firebug</a>.</li> +</ul> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/Tools" title="Tools">Tools</a></li> + <li><a href="/en-US/docs/Tools/Web_Console" title="Web Console">Web Console</a> — how the Web Console in Firefox handles console API calls</li> + <li><a href="/en-US/docs/Tools/Remote_Debugging">Remote debugging</a> — how to see console output when the debugging target is a mobile device</li> + <li><a href="/en-US/docs/Mozilla/Firefox_OS/Debugging/On-device_console_logging" title="/en-US/docs/Mozilla/Firefox_OS/Debugging/On-device_console_logging">On-device console logging</a> — how to do logging on Firefox OS devices</li> +</ul> + +<h3 id="Other_implementations">Other implementations</h3> + +<ul> + <li><a href="https://developers.google.com/chrome-developer-tools/docs/console-api">Google Chrome DevTools</a></li> + <li><a href="http://getfirebug.com/wiki/index.php/Console_API">Firebug</a></li> + <li><a href="http://msdn.microsoft.com/en-us/library/hh772173(v=vs.85).aspx">Internet Explorer</a></li> + <li><a href="https://developer.apple.com/library/safari/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/Console/Console.html">Safari</a></li> +</ul> diff --git a/files/zh-tw/web/api/css_object_model/determining_the_dimensions_of_elements/index.html b/files/zh-tw/web/api/css_object_model/determining_the_dimensions_of_elements/index.html new file mode 100644 index 0000000000..589300d041 --- /dev/null +++ b/files/zh-tw/web/api/css_object_model/determining_the_dimensions_of_elements/index.html @@ -0,0 +1,33 @@ +--- +title: Determining the dimensions of elements +slug: Web/API/CSS_Object_Model/Determining_the_dimensions_of_elements +translation_of: Web/API/CSS_Object_Model/Determining_the_dimensions_of_elements +--- +<p>{{APIRef("CSSOM View")}}</p> + +<p>There are several properties you can look at in order to determine the width and height of elements, and it can be tricky to determine which is the right one for your needs. This article is designed to help you make that decision. Note that all these properties are read-only. If you want to set the width and height of an element, use <span style="line-height: 1.5;"> </span><code style="font-style: normal; line-height: 1.5;"><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/width" style="line-height: 1.5;" title="The width CSS property specifies the width of the content area of an element. The content area is inside the padding, border, and margin of the element.">width</a> </code>and<code style="font-style: normal; line-height: 1.5;"> </code><code><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/height" title="The height CSS property specifies the height of the content area of an element. The content area is inside the padding, border, and margin of the element.">height</a>;</code><span style="line-height: 1.5;"> or, the overriding</span><span style="line-height: 1.5;"> </span><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/min-width" style="line-height: 1.5;" title="The min-width property is used to set the minimum width of a given element. It prevents the used value of the width property from becoming smaller than the value specified for min-width."><code>min-width</code></a><span style="line-height: 1.5;"> </span>and<span style="line-height: 1.5;"> </span><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/max-width" style="line-height: 1.5;" title="The max-width property is used to set the maximum width of a given element. It prevents the used value of the width property from becoming larger than the value specified for max-width."><code>max-width</code></a><span style="line-height: 1.5;">, </span>and<span style="line-height: 1.5;"> </span><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/min-height" style="line-height: 1.5;" title="The min-height CSS property is used to set the minimum height of a given element. It prevents the used value of the height property from becoming smaller than the value specified for min-height."><code>min-height</code></a><span style="line-height: 1.5;"> </span>and<span style="line-height: 1.5;"> </span><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/max-height" style="line-height: 1.5;" title="The max-height CSS property is used to set the maximum height of a given element. It prevents the used value of the height property from becoming larger than the value specified for max-height."><code>max-height</code></a><span style="line-height: 1.5;"> properties.</span></p> + +<h2 id="How_much_room_does_it_use_up.3F" name="How_much_room_does_it_use_up.3F">How much room does it use up?</h2> + +<p>If you need to know the total amount of space an element occupies, including the width of the visible content, scrollbars (if any), padding, and border, you want to use the <code><a href="/en/DOM/element.offsetWidth" title="en/DOM/element.offsetWidth">offsetWidth</a></code> and <code><a href="/en/DOM/element.offsetHeight" title="en/DOM/element.offsetHeight">offsetHeight</a></code> properties. Most of the time these are the same as width and height of <code><a href="/en/DOM/element.getBoundingClientRect" title="en/DOM/element.getBoundingClientRect">getBoundingClientRect()</a></code>, when there aren't any transforms applied to the element. In case of transforms, the <code>offsetWidth</code> and <code>offsetHeight</code> returns the element's layout width and height, while <code>getBoundingClientRect()</code> returns the rendering width and height. As an example, if the element has <code>width: 100px;</code> and <code>transform: scale(0.5);</code> the <code>getBoundingClientRect()</code> will return 50 as the width, while <code>offsetWidth</code> will return 100.</p> + +<p><img alt="Image:Dimensions-offset.png" class="internal" src="/@api/deki/files/186/=Dimensions-offset.png"></p> + +<h2 id="What.27s_the_size_of_the_displayed_content.3F" name="What.27s_the_size_of_the_displayed_content.3F">What's the size of the displayed content?</h2> + +<p>If you need to know how much space the actual displayed content takes up, including padding but not including the border, margins, or scrollbars, you want to use the <code><a href="/en/DOM/element.clientWidth" title="en/DOM/element.clientWidth">clientWidth</a></code> and <code><a href="/en/DOM/element.clientHeight" title="en/DOM/element.clientHeight">clientHeight</a></code> properties:</p> + +<p><img alt="Image:Dimensions-client.png" class="internal" src="/@api/deki/files/185/=Dimensions-client.png"></p> + +<h2 id="How_big_is_the_content.3F" name="How_big_is_the_content.3F">How big is the content?</h2> + +<p>If you need to know the actual size of the content, regardless of how much of it is currently visible, you need to use the <code><a href="/en/DOM/element.scrollWidth" title="en/DOM/element.scrollWidth">scrollWidth</a></code> and <code><a href="/en-US/docs/Web/API/Element.scrollHeight" title="en/DOM/element.scrollHeight">scrollHeight</a></code> properties. These return the width and height of the entire content of an element, even if only part of it is presently visible due to the use of scroll bars.</p> + +<p>For example, if a 600x400 pixel element is being displayed inside a 300x300 pixel scrollbox, <code>scrollWidth</code> will return 600 while <code>scrollHeight</code> will return 400.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a class="external" href="http://www.w3.org/TR/cssom-view/">http://www.w3.org/TR/cssom-view/</a></li> + <li><a href="https://docs.microsoft.com/en-us/previous-versions//hh781509(v=vs.85)">MSDN: Measuring Element Dimension and Location</a></li> +</ul> diff --git a/files/zh-tw/web/api/css_object_model/index.html b/files/zh-tw/web/api/css_object_model/index.html new file mode 100644 index 0000000000..e924a96301 --- /dev/null +++ b/files/zh-tw/web/api/css_object_model/index.html @@ -0,0 +1,131 @@ +--- +title: CSS Object Model +slug: Web/API/CSS_Object_Model +tags: + - API + - CSSOM + - NeedsTranslation + - Reference + - TopicStub +translation_of: Web/API/CSS_Object_Model +--- +<p>{{DefaultAPISidebar('CSSOM')}}</p> + +<p>The <strong>CSS Object Model</strong> is a set of APIs allowing to manipulate CSS from JavaScript. It is the pendant of DOM and HTML APIs, but for CSS. It allows to read and modify CSS style dynamically.</p> + +<h2 id="Reference">Reference</h2> + +<div class="index"> +<ul> + <li>{{domxref("AnimationEvent")}}</li> + <li>{{domxref("CaretPosition")}}</li> + <li>{{domxref("CSS")}}</li> + <li>{{domxref("CSSCharsetRule")}}</li> + <li>{{domxref("CSSConditionRule")}}</li> + <li>{{domxref("CSSCounterStyleRule")}}</li> + <li>{{domxref("CSSFontFaceRule")}}</li> + <li>{{domxref("CSSFontFeatureValuesMap")}}</li> + <li>{{domxref("CSSFontFeatureValuesRule")}}</li> + <li>{{domxref("CSSGroupingRule")}}</li> + <li>{{domxref("CSSImportRule")}}</li> + <li>{{domxref("CSSKeyframeRule")}}</li> + <li>{{domxref("CSSKeyframesRule")}}</li> + <li>{{domxref("CSSMarginRule")}}</li> + <li>{{domxref("CSSMediaRule")}}</li> + <li>{{domxref("CSSNamespaceRule")}}</li> + <li>{{domxref("CSSPageRule")}}</li> + <li>{{domxref("CSSRule")}}</li> + <li>{{domxref("CSSRuleList")}}</li> + <li>{{domxref("CSSStyleSheet")}}</li> + <li>{{domxref("CSSStyleDeclaration")}}</li> + <li>{{domxref("CSSSupportsRule")}}</li> + <li>{{domxref("CSSVariablesMap")}}</li> + <li>{{domxref("CSSViewportRule")}}</li> + <li>{{domxref("ElementCSSInlineStyle")}}</li> + <li>{{domxref("GeometryUtils")}}</li> + <li>{{domxref("GetStyleUtils")}}</li> + <li>{{domxref("LinkStyle")}}</li> + <li>{{domxref("MediaList")}}</li> + <li>{{domxref("MediaQueryList")}}</li> + <li>{{domxref("PseudoElement")}}</li> + <li>{{domxref("Screen")}}</li> + <li>{{domxref("StyleSheet")}}</li> + <li>{{domxref("StyleSheetList")}}</li> + <li>{{domxref("TransitionEvent")}}</li> +</ul> +</div> + +<p>Several other interfaces are also extended by the CSSOM-related specifications: {{domxref("Document")}}, {{domxref("Window")}}, {{domxref("Element")}}, {{domxref("HTMLElement")}}, {{domxref("HTMLImageElement")}}, {{domxref("Range")}}, {{domxref("MouseEvent")}}, and {{domxref("SVGElement")}}.</p> + +<h2 id="Tutorials">Tutorials</h2> + +<ul> + <li><a href="/en-US/docs/Determining_the_dimensions_of_elements">Determining the dimensions of elements</a> (it needs some updating as it was made in the DHTML/Ajax era).</li> + <li><a href="/en-US/docs/WebAPI/Managing_screen_orientation">Managing screen orientation</a></li> +</ul> + +<h2 id="Specifications">Specifications</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("CSSOM")}}</td> + <td>{{Spec2("CSSOM")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("CSSOM View")}}</td> + <td>{{Spec2("CSSOM View")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("Screen Orientation")}}</td> + <td>{{Spec2("Screen Orientation")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("CSS3 Fonts")}}</td> + <td>{{Spec2("CSS3 Fonts")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("CSS3 Animations")}}</td> + <td>{{Spec2("CSS3 Animations")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("CSS3 Transitions")}}</td> + <td>{{Spec2("CSS3 Transitions")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("CSS3 Variables")}}</td> + <td>{{Spec2("CSS3 Variables")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("CSS3 Conditional")}}</td> + <td>{{Spec2("CSS3 Conditional")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("CSS3 Device")}}</td> + <td>{{Spec2("CSS3 Device")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("CSS3 Counter Styles")}}</td> + <td>{{Spec2("CSS3 Counter Styles")}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility_notes">Browser compatibility notes</h2> + +<p>All these features have been added little by little over the years to the different browsers: it was a quite complex process that can't be summarized in a simple table. Please refer to the specific interfaces for its availability.</p> diff --git a/files/zh-tw/web/api/css_object_model/managing_screen_orientation/index.html b/files/zh-tw/web/api/css_object_model/managing_screen_orientation/index.html new file mode 100644 index 0000000000..806ac2d047 --- /dev/null +++ b/files/zh-tw/web/api/css_object_model/managing_screen_orientation/index.html @@ -0,0 +1,172 @@ +--- +title: 控制畫面方向 +slug: Web/API/CSS_Object_Model/Managing_screen_orientation +translation_of: Web/API/CSS_Object_Model/Managing_screen_orientation +--- +<p>{{SeeCompatTable}}{{APIRef}}</p> + +<h2 id="摘要">摘要</h2> + +<p>畫面方向（Screen Orientation）與<a href="https://developer.mozilla.org/zh-TW/docs/WebAPI/Detecting_device_orientation" title="/zh-TW/docs/WebAPI/Detecting_device_orientation">裝置方向（Device Orientation）</a>略有不同。有時甚至裝置本身不具備方向偵測功能，但裝置的螢幕仍搭載方向功能。如果裝置可測知本身的方向又能控制畫面方向，就能隨時配合 Web Apps 而達到最佳效果。</p> + +<p>現有 2 種方法可處理畫面的方向，但均需搭配 CSS 與 JavaScript。第一種方法就是方向的 <a href="https://developer.mozilla.org/zh-TW/docs/CSS/Media_queries#orientation" title="en-US/CSS/Media queries#orientation">Media Query</a>。根據瀏覽器視窗為橫放（寬度大於高度）或直放（高度大於寬度）狀態，而透過 CSS 調整網頁內容的配置。</p> + +<p>第二種方法就是 JavaScript Screen Orientation API，可取得畫面目前的方向並進一步鎖定。</p> + +<h2 id="根據方向而調整配置">根據方向而調整配置</h2> + +<p>方向改變最常見的情形之一，就是根據裝置的方向而修正內容的配置方式。舉例來說，你可能想將按鈕列拉到與裝置螢幕等長。而透過 Media Query 即可輕鬆達到此效果。</p> + +<p>來看看下列 HTML 程式碼範例：</p> + +<pre class="brush: html"><ul id="toolbar"> + <li>A</li> + <li>B</li> + <li>C</li> +</ul> + +<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis lacinia nisi nec sem viverra vitae fringilla nulla ultricies. In ac est dolor, quis tincidunt leo. Cras commodo quam non tortor consectetur eget rutrum dolor ultricies. Ut interdum tristique dapibus. Nullam quis malesuada est.</p> +</pre> + +<p>CSS 將根據方向的 Media Query，處理畫面方向的特殊樣式：</p> + +<pre class="brush: css">/* First let's define some common styles */ + +html, body { + width : 100%; + height: 100%; +} + +body { + border: 1px solid black; + + -moz-box-sizing: border-box; + box-sizing: border-box; +} + +p { + font : 1em sans-serif; + margin : 0; + padding: .5em; +} + +ul { + list-style: none; + + font : 1em monospace; + margin : 0; + padding: .5em; + + -moz-box-sizing: border-box; + box-sizing: border-box; + + background: black; +} + +li { + display: inline-block; + margin : 0; + padding: 0.5em; + background: white; +} +</pre> + +<p>在設定某些通用的樣式之後，即可針對方向定義特殊條件：</p> + +<pre class="brush: css">/* For portrait, we want the tool bar on top */ + +@media screen and (orientation: portrait) { + #toolbar { + width: 100%; + } +} + +/* For landscape, we want the tool bar stick on the left */ + +@media screen and (orientation: landscape) { + #toolbar { + position: fixed; + width: 2.65em; + height: 100%; + } + + p { + margin-left: 2em; + } + + li + li { + margin-top: .5em; + } +} +</pre> + +<p>結果如下所示（若無法顯示，可至本文右上角切換回英文原文觀看）：</p> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Portrait</th> + <th scope="col">Landscape</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{ EmbedLiveSample('Adjusting_layout_based_on_the_orientation', 180, 350) }}</td> + <td>{{ EmbedLiveSample('Adjusting_layout_based_on_the_orientation', 350, 180) }}</td> + </tr> + </tbody> +</table> + +<div class="note"> +<p><strong>注意：</strong>方向 Media Query 其實是以瀏覽器視窗 (或 iframe) 的方向為準，而非裝置本身的方向。</p> +</div> + +<h2 id="鎖定畫面方向">鎖定畫面方向</h2> + +<div class="warning"> +<p><strong>警告：</strong>此 API 仍屬實驗性質，目前仍具備 <code>moz</code> 前綴而僅能用於 <a href="https://developer.mozilla.org/zh-TW/docs/Mozilla/Firefox_OS" title="/zh-TW/docs/Mozilla/Firefox_OS">Firefox OS</a> 與 <a href="https://developer.mozilla.org/zh-TW/docs/Mozilla/Firefox_for_Android" title="/zh-TW/docs/Mozilla/Firefox_for_Android">Firefox for Android</a>，而 Windows 8.1 以上版本的 Internet Explorer 則使用 <code>ms</code> 前綴。</p> +</div> + +<p>某些裝置（主要為行動裝置）可根據本身方向而動態改變畫面的方向，讓使用者隨時閱讀畫面上的資訊。這種動作對文字類的內容影響不大，但某些內容就無法順利套用此功能。舉例來說，若遊戲需要裝置方向的相關資訊，就可能因為方向變化而發生混亂情形。</p> + +<p>而 Screen Orientation API 即可用以避免或處理這類變化。</p> + +<h3 id="監聽方向變化">監聽方向變化</h3> + +<p>只要裝置改變了畫面方向與本身方向，就會觸發 {{event("orientationchange")}} 事件，再由 {{domxref("Screen.orientation")}} 屬性讀取之。</p> + +<pre class="brush: js">screen.addEventListener("orientationchange", function () { + console.log("The orientation of the screen is: " + screen.orientation); +}); +</pre> + +<h3 id="避免方向改變">避免方向改變</h3> + +<p>任何 Web Apps 均可鎖定畫面以符合本身需求。{{domxref("Screen.lockOrientation()")}} 函式可鎖定畫面方向；{{domxref("Screen.unlockOrientation()")}} 函式可解鎖畫面方向。</p> + +<p>{{domxref("Screen.lockOrientation()")}} 將接受一組字串或系列字串，以定義畫面鎖定的方向。有效字串為：「<code>portrait-primary</code>」、「<code>portrait-secondary</code>」、「<code>landscape-primary</code>」、「<code>landscape-secondary</code>」、「<code>portrait</code>」、「<code>landscape</code>」。另可參閱 {{domxref("Screen.lockOrientation")}} 進一步了解這些有效值。</p> + +<pre class="brush: js">screen.lockOrientation('landscape');</pre> + +<div class="note"> +<p><strong>注意：</strong>畫面鎖定功能將依 Web Apps 而有所不同。如果 App A 鎖定為 <code>landscape</code>；App B 鎖定為 <code>portrait，則此兩款 Apps 均將維持自己的方向。所以不論如何切換</code> A 與 B，均不會觸發 {{event("orientationchange")}} 事件。</p> + +<p>但若必須改變方向以滿足畫面鎖定的需求，則鎖定方向時就會觸發 {{event("orientationchange")}} 事件。</p> +</div> + +<h2 id="Firefox_OS_and_Android_Orientation_lock_using_the_manifest">Firefox OS and Android: Orientation lock using the manifest</h2> + +<p>For a Firefox OS and Firefox Android (soon to work on Firefox desktop too) specific way to lock orientation, you can set the <a href="/en-US/Apps/Build/Manifest#orientation">orientation</a> field in app's your manifest file, for example:</p> + +<pre class="brush: json">"orientation": "portrait"</pre> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("Screen.orientation")}}</li> + <li>{{domxref("Screen.lockOrientation()")}}</li> + <li>{{domxref("Screen.unlockOrientation()")}}</li> + <li>{{domxref("Screen.onorientationchange")}}</li> + <li><a href="/zh-TW/docs/CSS/Media_queries#orientation" title="en-US/CSS/Media queries#orientation">方向的 Media Query</a></li> + <li><a class="external" href="http://hacks.mozilla.org/2009/06/media-queries/" title="http://hacks.mozilla.org/2009/06/media-queries/">Firefox 3.5 的 Media Queries 簡介</a></li> +</ul> diff --git a/files/zh-tw/web/api/css_object_model/using_dynamic_styling_information/index.html b/files/zh-tw/web/api/css_object_model/using_dynamic_styling_information/index.html new file mode 100644 index 0000000000..fa020403aa --- /dev/null +++ b/files/zh-tw/web/api/css_object_model/using_dynamic_styling_information/index.html @@ -0,0 +1,132 @@ +--- +title: 使用動態樣式資訊 +slug: Web/API/CSS_Object_Model/Using_dynamic_styling_information +translation_of: Web/API/CSS_Object_Model/Using_dynamic_styling_information +--- +<p>The CSS Object Model (CSSOM), part of the DOM, exposes specific interfaces allowing manipulation of a wide amount of information regarding CSS. Initially defined in the <em>DOM Level 2 Style</em> recommendation, these interfaces forms now a specification, <em>CSS Object Model (CSSOM)</em> which aims at superseding it.</p> + +<p>In many cases, and where possible, it really is best practice to dynamically manipulate classes via the {{ domxref("element.className", "className") }} property since the ultimate appearance of all of the styling hooks can be controlled in a single stylesheet. One's JavaScript code also becomes cleaner since instead of being dedicated to styling details, it can focus on the overall semantics of each section it is creating or manipulating, leaving the precise style details to the stylesheet. However, there are cases where actually obtaining or manipulating the rules can be useful (whether for whole stylesheets or individual elements), and that is described in further detail below. Note also that, as with individual element's DOM styles, when speaking of manipulating the stylesheets, this is not actually manipulating the physical document(s), but merely the internal representation of the document.</p> + +<p>The basic <code>style</code> object exposes the {{domxref("Stylesheet")}} and the {{domxref("CSSStylesheet")}} interfaces. Those interfaces contain members like <code>insertRule</code>, <code>selectorText</code>, and <code>parentStyleSheet</code> for accessing and manipulating the individual style rules that make up a CSS stylesheet.</p> + +<p>To get to the <code>style</code> objects from the <code>document</code>, you can use the {{domxref("document.styleSheets")}} property and access the individual objects by index (e.g., <code>document.styleSheets[0]</code> is the first stylesheet defined for the document, etc.).</p> + +<h2 id="Modify_a_stylesheet_rule" name="Modify_a_stylesheet_rule">透過 CSSOM 修改樣式表規則</h2> + +<pre class="brush: html" style="font-size: 14px;"><html> +<head> +<title>Modifying a stylesheet rule with CSSOM</title> +<style type="text/css"> +body { + background-color: red; +} +</style> +<script type="text/javascript"> +var stylesheet = document.styleSheets[1]; +stylesheet.cssRules[0].style.backgroundColor="blue"; +</script> +</head> +<body> +The stylesheet declaration for the body's background color is modified via JavaScript. +</body> +</html></pre> + +<p>{{ EmbedLiveSample('Modify_a_stylesheet_rule') }}</p> + +<p>The list of properties available in the DOM from the style property is given on the <a href="/en-US/docs/DOM/CSS" title="en/DOM/CSS">DOM CSS Properties List</a> page.</p> + +<p>To modify styles to a document using CSS syntax, one can insert rules or insert {{HTMLElement("style")}} tags whose <code>innerHTML</code> property is set to the desired CSS.</p> + +<h2 id="Modify_an_element_style" name="Modify_an_element_style">修改元素的樣式</h2> + +<p>The element {{domxref("HTMLElement.style", "style")}} property (see also the section "DOM Style Object" below) can also be used to get and set the styles on an element. However, this property only returns style attributes that have been set <em>in-line</em> (e.g, <code><td style="background-color: lightblue"></code> returns the string "<code>background-color:lightblue</code>", or directly for that element using <code>element.style.propertyName</code>, even though there may be other styles on the element from a stylesheet).</p> + +<p>Also, when you set this property on an element, you override and erase any styles that have been set elsewhere for that element's particular property you are setting. Setting the border property, for example, will override settings made elsewhere for that element's border property in the head section, or external style sheets. However, this will not affect any other property declarations for that element's styles, such as padding or margin or font, for example.</p> + +<p>To change a particular element's style, you can adapt the following example for the element(s) you want to style.</p> + +<pre class="brush: html"><html> +<head> +<title>simple style example</title> + +<script type="text/javascript"> + +function alterStyle(elem) { + elem.style.background = 'green'; +} + +function resetStyle(elemId) { + elem = document.getElementById(elemId); + elem.style.background = 'white'; +} +</script> + +<style type="text/css"> +#p1 { + border: solid blue 2px; +} +</style> +</head> + +<body> + +<!-- passes a reference to the element's object as parameter 'this'. --> +<p id="p1" onclick="alterStyle(this);"> + Click here to change background color. +</p> + +<!-- passes the 'p1' id of another element's style to modify. --> +<button onclick="resetStyle('p1');">Reset background color</button> + +</body> +</html> +</pre> + +<p>{{ EmbedLiveSample('Modify_an_element_style') }}</p> + +<p>The {{domxref("window.getComputedStyle", "getComputedStyle()")}} method on the <code>document.defaultView</code> object returns all styles that have actually been computed for an element. See <a href="/en/Gecko_DOM_Reference/Examples#Example_6:_getComputedStyle" title="en/Gecko_DOM_Reference/Examples#Example_6:_getComputedStyle">Example 6: getComputedStyle</a> in the examples chapter for more information on how to use this method.</p> + +<h2 id="DOM_Style_Object" name="DOM_Style_Object">DOM Style Object</h2> + +<p>The <code>style</code> object represents an individual style statement. Unlike the individual rules available from the <code><a href="/en/DOM/document.styleSheets" title="en/DOM/document.styleSheets">document.styleSheets</a></code> collection, the style object is accessed from the <code>document</code> or from the elements to which that style is applied. It represents the <em>in-line</em> styles on a particular element.</p> + +<p>More important than the two properties noted here is the use of the <code>style</code> object to set individual style properties on an element:</p> + +<div id="DOM_Style_Object_code_sample"> +<pre class="brush: html"><!DOCTYPE html> +<html> + <head> + <title>style Property Example</title> + <link rel="StyleSheet" href="example.css" type="text/css"> + <script type="text/javascript"> + function stilo() { + document.getElementById('d').style.color = 'orange'; + } + function resetStyle() { + document.getElementById('d').style.color = 'black'; + } + </script> + </head> + + <body> + <div id="d" class="thunder">Thunder</div> + <button onclick="stilo()">Click here to change text color</button> + <button onclick="resetStyle()">Reset text color</button> + </body> +</html> +</pre> +</div> + +<p>{{ EmbedLiveSample('DOM_Style_Object_code_sample') }}</p> + +<p>The <strong>media</strong> and <strong>type</strong> of the style may or may not be given.</p> + +<h3 id="DOM_Style_Object_SetAttribue" name="DOM_Style_Object_SetAttribue">使用 setAttribute 方法</h3> + +<p>Note that you can also change style of an element by getting a reference to it and then use its <code><a href="/en/DOM/element.setAttribute" title="en/DOM/element.setAttribute">setAttribute</a></code> method to specify the CSS property and its value.</p> + +<pre class="brush: js">var el = document.getElementById('some-element'); +el.setAttribute('style', 'background-color:darkblue;'); +</pre> + +<p>Be aware, however, that <code>setAttribute</code> removes all other style properties that may already have been defined in the element's style object. If the <code><var>some-element</var></code> element above had an in–line style attribute of say <code>style="font-size: 18px"</code>, that value would be removed by the use of <code>setAttribute</code>.</p> diff --git a/files/zh-tw/web/api/cssstyledeclaration/index.html b/files/zh-tw/web/api/cssstyledeclaration/index.html new file mode 100644 index 0000000000..8893e225d6 --- /dev/null +++ b/files/zh-tw/web/api/cssstyledeclaration/index.html @@ -0,0 +1,90 @@ +--- +title: CSSStyleDeclaration +slug: Web/API/CSSStyleDeclaration +translation_of: Web/API/CSSStyleDeclaration +--- +<p>{{ APIRef("CSSOM") }}</p> + +<h2 id="Summary" name="Summary">概要</h2> + +<p><code>CSSStyleDeclaration</code> 表示了一個 CSS 屬性名值對（property-value pairs）的集合。它被用於幾個 API 當中：</p> + +<ul> + <li>{{domxref("HTMLElement.style")}} - to manipulate the style of a single element (<elem style="...">);</li> + <li>(TODO: reword) is an interface to the <a class="external" href="http://www.w3.org/TR/1998/REC-CSS2-19980512/syndata.html#block">declaration block</a> returned by the <code><a href="/en/DOM/cssRule.style" rel="internal" title="en/DOM/cssRule.style">style</a></code> property of a <code><a href="/en/DOM/cssRule" rel="internal" title="en/DOM/cssRule">cssRule</a></code> in a <a href="/en/DOM/stylesheet" rel="internal" title="en/DOM/stylesheet">stylesheet</a>, when the rule is a <a href="/en/DOM/cssRule#CSSStyleRule" title="en/DOM/cssRule#CSSStyleRule">CSSStyleRule</a>.</li> + <li><code>CSSStyleDeclaration</code> is also a <strong>read-only</strong> interface to the result of <a href="/en/DOM/window.getComputedStyle" title="en/DOM/window.getComputedStyle">window.getComputedStyle</a>().</li> +</ul> + +<h2 id="Syntax" name="Syntax">屬性</h2> + +<dl> + <dt>{{domxref("CSSStyleDeclaration.cssText")}}</dt> + <dd>Textual representation of the declaration block. Setting this attribute changes the style.</dd> + <dt>{{domxref("CSSStyleDeclaration.length")}} {{readonlyInline}}</dt> + <dd>The number of properties. See the {{domxref("CSSStyleDeclaration.item", 'item()')}} method below.</dd> + <dt>{{domxref("CSSStyleDeclaration.parentRule")}} {{readonlyInline}}</dt> + <dd>The containing {{domxref("CSSRule")}}.</dd> +</dl> + +<h2 id="Syntax" name="Syntax">方法</h2> + +<dl> + <dt>{{domxref("CSSStyleDeclaration.getPropertyPriority()")}}</dt> + <dd>Returns the optional priority, "important".</dd> + <dt>{{domxref("CSSStyleDeclaration.getPropertyValue()")}}</dt> + <dd>Returns the property value given a property name.</dd> + <dt>{{domxref("CSSStyleDeclaration.item()")}}</dt> + <dd>Returns a property name.</dd> + <dt>{{domxref("CSSStyleDeclaration.removeProperty()")}}</dt> + <dd>Removes a property from the CSS declaration block.</dd> + <dt>{{domxref("CSSStyleDeclaration.setProperty()")}}</dt> + <dd>Modifies an existing CSS property or creates a new CSS property in the declaration block/.</dd> + <dt>{{domxref("CSSStyleDeclaration.getPropertyCSSValue()")}} {{obsolete_inline}}</dt> + <dd><span style="color: #ff0000;">Only supported via getComputedStyle in Firefox.</span> Returns the property value as a {{ domxref("CSSPrimitiveValue") }} or <code>null</code> for <a href="/en/CSS/Shorthand_properties" title="en/Guide to Shorthand CSS">shorthand properties</a>.</dd> +</dl> + +<h2 id="Example" name="Example">範例</h2> + +<pre class="brush: js">var styleObj = document.styleSheets[0].cssRules[0].style; +console.log(styleObj.cssText); + +for (var i = styleObj.length; i--;) { + var nameString = styleObj[i]; + styleObj.removeProperty(nameString); +} + +console.log(styleObj.cssText);</pre> + +<h2 id="Notes" name="Notes">備註</h2> + +<p>The declaration block is that part of the style rule that appears within the braces and that actually provides the style definitions (for the selector, the part that comes before the braces).</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/en-US/docs/Web/CSS/CSS_Properties_Reference" title="/en-US/docs/Web/CSS/CSS_Properties_Reference">DOM CSS Properties</a></li> +</ul> + +<h2 id="Specification" name="Specification">規範</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('CSSOM', '#the-cssstyledeclaration-interface', 'CSSStyleDeclaration')}}</td> + <td>{{Spec2('CSSOM')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM2 Style', 'css.html#CSS-CSSStyleDeclaration', 'CSSPrimitiveValue')}}</td> + <td>{{Spec2('DOM2 Style')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> diff --git a/files/zh-tw/web/api/cssstylesheet/index.html b/files/zh-tw/web/api/cssstylesheet/index.html new file mode 100644 index 0000000000..01abf1a942 --- /dev/null +++ b/files/zh-tw/web/api/cssstylesheet/index.html @@ -0,0 +1,187 @@ +--- +title: CSSStyleSheet +slug: Web/API/CSSStyleSheet +tags: + - API + - CSSOM + - NeedsTranslation + - Reference + - TopicStub +translation_of: Web/API/CSSStyleSheet +--- +<div>{{APIRef("CSSOM")}}</div> + +<p>The <strong><code>CSSStyleSheet</code></strong> interface represents a single <a href="/en-US/docs/Web/CSS">CSS</a> style sheet. It inherits properties and methods from its parent, {{domxref("StyleSheet")}}.</p> + +<p>A style sheet consists of <em>{{domxref("CSSRule", "rules", "", 1)}}</em>, such as <em>{{domxref("CSSStyleRule", "style rules", "", 1)}}</em><em> </em>("<code>h1,h2 { font-size: 16pt }"</code>), various <em>at-rules</em> (<code>@import</code>, <code>@media</code>, ...), etc. This interface lets you inspect and modify the list of rules in the stylesheet.</p> + +<p>See the {{anch("Notes")}} section for the various ways a CSSStyleSheet object can be obtained.</p> + +<h2 id="Properties">Properties</h2> + +<p><em>Inherits properties from its parent, {{domxref("StyleSheet")}}.</em></p> + +<dl> + <dt id="cssRules">{{domxref("CSSStyleSheet.cssRules")}}</dt> + <dd>Returns a live {{domxref("CSSRuleList")}}, listing the {{domxref("CSSRule")}} objects in the style sheet.<br> + This is normally used to access individual rules like this:<br> + <code> styleSheet.cssRules[i] // where i = 0..cssRules.length-1</code><br> + To add or remove items in <code>cssRules</code>, use the <code>CSSStyleSheet</code>'s <code>deleteRule()</code> and <code>insertRule()</code> methods, described below.</dd> + <dt id="ownerRule">{{domxref("CSSStyleSheet.ownerRule")}}</dt> + <dd>If this style sheet is imported into the document using an {{cssxref("@import")}} rule, the <code>ownerRule</code> property will return that {{domxref("CSSImportRule")}}, otherwise it returns <code>null</code>.</dd> +</dl> + +<h2 id="Methods">Methods</h2> + +<p><em>Inherits methods from its parent, {{domxref("Stylesheet")}}.</em></p> + +<dl> + <dt id="deleteRule">{{domxref("CSSStyleSheet.deleteRule()")}}</dt> + <dd>Deletes a rule at the specified position from the style sheet.</dd> + <dt id="insertRule">{{domxref("CSSStyleSheet.insertRule()")}}</dt> + <dd>Inserts a new rule at the specified position in the style sheet, given the textual representation of the rule.</dd> +</dl> + +<h2 id="Notes">Notes</h2> + +<p>In some browsers, if a stylesheet is loaded from a different domain, calling <code>cssRules</code> results in <code>SecurityError</code>.</p> + +<p>A stylesheet is associated with at most one {{domxref("Document")}}, which it applies to (unless {{domxref("StyleSheet.disabled", "disabled", "", 1)}}). A list of <code>CSSStyleSheet</code> objects for a given document can be obtained using the {{domxref("document.styleSheets")}} property. A specific style sheet can also be accessed from its <em>owner</em> object (<code>Node</code> or <code>CSSImportRule</code>), if any.</p> + +<p>A <code>CSSStyleSheet</code> object is created and inserted into the document's <code>styleSheets</code> list automatically by the browser, when a style sheet is loaded for a document. As the {{domxref("document.styleSheets")}} list cannot be modified directly, there's no useful way to create a new <code>CSSStyleSheet</code> object manually (although <a href="http://tabatkins.github.io/specs/construct-stylesheets/">Constructable Stylesheet Objects</a> might get added to the Web APIs at some point). To create a new stylesheet, insert a {{HTMLElement("style")}} or {{HTMLElement("link")}} element into the document.</p> + +<p>A (possibly incomplete) list of ways a style sheet can be associated with a document follows:</p> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Reason for the style sheet to be associated with the document</th> + <th scope="col">Appears in <code>document.<br> + styleSheets</code> list</th> + <th scope="col">Getting the owner element/rule given the style sheet object</th> + <th scope="col">The interface for the owner object</th> + <th scope="col">Getting the CSSStyleSheet object from the owner</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{HTMLElement("style")}} and {{HTMLElement("link")}} elements in the document</td> + <td>Yes</td> + <td>{{domxref("StyleSheet.ownerNode", ".ownerNode")}}</td> + <td>{{domxref("HTMLLinkElement")}},<br> + {{domxref("HTMLStyleElement")}},<br> + or {{domxref("SVGStyleElement")}}</td> + <td>{{domxref("LinkStyle.sheet", ".sheet")}}</td> + </tr> + <tr> + <td>CSS {{cssxref("@import")}} rule in other style sheets applied to the document</td> + <td>Yes</td> + <td>{{domxref("CSSStyleSheet.ownerRule", ".ownerRule")}}</td> + <td>{{domxref("CSSImportRule")}}</td> + <td>{{domxref("CSSImportRule.styleSheet", ".styleSheet")}}</td> + </tr> + <tr> + <td><code><?xml-stylesheet ?></code> processing instruction in the (non-HTML) document</td> + <td>Yes</td> + <td>{{domxref("StyleSheet.ownerNode", ".ownerNode")}}</td> + <td>{{domxref("ProcessingInstruction")}}</td> + <td>{{domxref("LinkStyle.sheet", ".sheet")}}</td> + </tr> + <tr> + <td>HTTP Link Header</td> + <td>Yes</td> + <td><em>N/A</em></td> + <td>N/A</td> + <td>N/A</td> + </tr> + <tr> + <td>User agent (default) style sheets</td> + <td>No</td> + <td>N/A</td> + <td>N/A</td> + <td>N/A</td> + </tr> + </tbody> +</table> + +<h2 id="Specifications">Specifications</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th>Specification</th> + <th>Status</th> + <th>Comment</th> + </tr> + <tr> + <td>{{SpecName("CSSOM", "#cssstylesheet", 'CSSStyleSheet')}}</td> + <td>{{Spec2("CSSOM")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("DOM2 Style", "css.html#CSS-CSSStyleSheet", "CSSStyleSheet")}}</td> + <td>{{Spec2("DOM2 Style")}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{CompatibilityTable}}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>9.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/CSS_Object_Model/Using_dynamic_styling_information">Using dynamic styling information</a></li> +</ul> diff --git a/files/zh-tw/web/api/cssstylesheet/insertrule/index.html b/files/zh-tw/web/api/cssstylesheet/insertrule/index.html new file mode 100644 index 0000000000..3cd8ba5a87 --- /dev/null +++ b/files/zh-tw/web/api/cssstylesheet/insertrule/index.html @@ -0,0 +1,219 @@ +--- +title: CSSStyleSheet.insertRule() +slug: Web/API/CSSStyleSheet/insertRule +translation_of: Web/API/CSSStyleSheet/insertRule +--- +<div>{{APIRef("CSSOM")}} </div> + +<p><strong>CSSStyleSheet.insertRule() </strong>方法新增一個新的 CSS 規則，到當前的樣式表，他伴隨著一些<a href="#Restrictions">限制</a>. </p> + +<p>更明確的說，雖然 <strong>insertRule()</strong> 只是一個 {{domxref("CSSStyleSheet")}} 的方法， 他實際上插入這份規則到 {{domxref("CSSStyleSheet")}}.<em>cssRules</em>, 在 {{domxref("CSSRuleList")}} 之中。</p> + +<p>這份規則，必須包含的內容，取決於它的類型： 對於規則集 (rule-sets)，規則同時指定了選擇器和样式聲明。 對於規則 (at-rules)，規則同時指定 at 標識符（ at-identifier ）和規則內容。</p> + +<h2 id="Syntax"><em><em>Syntax</em></em></h2> + +<pre class="syntaxbox"><em> +<em> +<var>stylesheet</var>.insertRule(<var>rule</var>[, <var>index</var>])</em></em></pre> + +<h3 id="Parameters"><em><em>Parameters</em></em></h3> + +<dl> + <dt><em><em>rule</em></em></dt> + <dd><em><em>一個 {{domxref("DOMString")}} 包含要被插入的規則，這份規則同時指定了選擇器（ <a href="/en-US/docs/Web/Guide/CSS/Getting_Started/Selectors">selector</a> ）和样式聲明，或 at 標識符 (at-identifier ) 和規則內容。</em></em></dd> + <dt><em><em>index {{optional_inline}}</em></em></dt> + <dd> + <p><em><em>無符號整數，代表在 <em><em>{{domxref("CSSStyleSheet")}}<em>.</em>cssRules </em></em>中插入的位置，其中 index-0 是第一個規則，而 index-max 就是最後一個規則，並且與 CSSStyleSheet 的長度相同。cssRules 在舊的實現中是必需的。查詢「瀏覽器兼容」取得詳細信息。 默認值為 0。</em></em></p> + </dd> +</dl> + +<h3 id="Return_value"><em><em><em><em>Return value</em></em></em></em></h3> + +<p><em><em><em><em>The index within the style sheet's rule-list of the newly inserted rule.</em></em></em></em></p> + +<h3 id="Restrictions_限制"><em><em><em><em>Restrictions 限制</em></em></em></em></h3> + +<p><em><em>CSS 樣式表規則列表，有一些直覺的、和不是那麼直覺的<a href="https://drafts.csswg.org/cssom/#insert-a-css-rule">限制</a> ，影響著規則的插入方式和位置。<br> + 違反這些可能會導致 DOM 異常 ({{domxref("DOMException")}}) 引發錯誤。</em></em></p> + +<ul> + <li><em><em><em><em>如果 index > 樣式表中規則數量 (`CSSRuleList.length`)，他會中止，顯示 IndexSizeError (索引大小錯誤)。</em></em></em></em></li> + <li><em><em><em><em>如果 rule 無法在索引 0 插入，因為一些 CSS 因素的限制，他會中止，顯示 HierarchyRequestError (層次結構請求錯誤)。</em></em></em></em></li> + <li><em><em><em><em>如果規則參數中給出多個規則，他會中止，顯示 SyntaxError (語法錯誤)。</em></em></em></em></li> + <li><em><em><em><em>如果嘗試在樣式規則之後插入 `@import at-rule`，他會中止，顯示 HierarchyRequestError (層次結構請求錯誤)。</em></em></em></em></li> + <li><em><em><em><em>如果規則是 `@namespace at-rule`，且列表不只有 `@import at-rules` 和 / 或 `@namespace at-rules`他會中止，顯示 InvalidStateError (狀態錯誤無效)。</em></em></em></em></li> +</ul> + +<h2 id="Examples">Examples</h2> + +<h3 id="Example_1">Example 1</h3> + +<pre class="brush: js">// push a new rule onto the top of my stylesheet +myStyle.insertRule("#blanc { color: white }", 0); +</pre> + +<h3 id="Example_2">Example 2</h3> + +<pre class="brush: js">/** + * Add a stylesheet rule to the document (may be better practice, however, + * to dynamically change classes, so style information can be kept in + * genuine stylesheets (and avoid adding extra elements to the DOM)) + * Note that an array is needed for declarations and rules since ECMAScript does + * not afford a predictable object iteration order and since CSS is + * order-dependent (i.e., it is cascading); those without need of + * cascading rules could build a more accessor-friendly object-based API. + * @param {Array} rules Accepts an array of JSON-encoded declarations + * @example +addStylesheetRules([ + ['h2', // Also accepts a second argument as an array of arrays instead + ['color', 'red'], + ['background-color', 'green', true] // 'true' for !important rules + ], + ['.myClass', + ['background-color', 'yellow'] + ] +]); + */ +function addStylesheetRules (rules) { + var styleEl = document.createElement('style'), + styleSheet; + + // Append style element to head + document.head.appendChild(styleEl); + + // Grab style sheet + styleSheet = styleEl.sheet; + + for (var i = 0, rl = rules.length; i < rl; i++) { + var j = 1, rule = rules[i], selector = rules[i][0], propStr = ''; + // If the second argument of a rule is an array of arrays, correct our variables. + if (Object.prototype.toString.call(rule[1][0]) === '[object Array]') { + rule = rule[1]; + j = 0; + } + + for (var pl = rule.length; j < pl; j++) { + var prop = rule[j]; + propStr += prop[0] + ':' + prop[1] + (prop[2] ? ' !important' : '') + ';\n'; + } + + // Insert CSS Rule + styleSheet.insertRule(selector + '{' + propStr + '}', styleSheet.cssRules.length); + } +}</pre> + +<h2 id="Specifications">Specifications</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('CSSOM', '#dom-cssstylesheet-insertrule', 'CSSStyleSheet.insertRule')}}</td> + <td>{{Spec2('CSSOM')}}</td> + <td>No change from {{SpecName('DOM2 Style')}}.</td> + </tr> + <tr> + <td>{{SpecName('DOM2 Style', 'css.html#CSS-CSSStyleSheet-insertRule', 'CSSStyleSheet.insertRule')}}</td> + <td>{{Spec2('DOM2 Style')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{CompatibilityTable}}</p> + +<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>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>9</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>index</code> is optional</td> + <td>{{CompatChrome(60)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatOpera(47)}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android Webview</th> + <th>Chrome for Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>index</code> is optional</td> + <td>{{CompatChrome(60)}}</td> + <td>{{CompatChrome(60)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatOperaMobile(47)}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h3 id="Legacy_browser_support">Legacy browser support</h3> + +<ul> + <li> + <h4 id="Internet_Explorer_-_pre_v9"><strong>Internet Explorer - pre v9</strong></h4> + <strong>addRule</strong>(<var>selector</var>, <var>rule</var> [, <var>index</var>]); -- Example:<code> addRule('pre', 'font: 14px verdana'); // add rule at end</code><br> + <br> + <em>Also note the non-standard <code><a class="external" href="http://www.quirksmode.org/dom/w3c_css.html#change">removeRule()</a> </code> and <code><a class="external" href="http://www.quirksmode.org/dom/w3c_css.html#access">.rules</a> </code> instead of {{domxref("CSSStyleSheet.deleteRule","deleteRule()")}} and {{domxref("CSSStyleSheet",".cssRules")}} respectively.</em></li> +</ul> + +<h2 id="See_also">See also</h2> + +<ul> + <li>{{domxref("CSSStyleSheet.deleteRule")}}</li> + <li><a class="external" href="http://www-archive.mozilla.org/docs/web-developer/css1technote/css1tojs.html#priority">Cross-Browser CSS-rules ordering (CSS1)</a></li> + <li><a class="external" href="http://www.quirksmode.org/dom/w3c_css.html">Quirksmode - CSS</a></li> +</ul> diff --git a/files/zh-tw/web/api/customevent/customevent/index.html b/files/zh-tw/web/api/customevent/customevent/index.html new file mode 100644 index 0000000000..0accf247e5 --- /dev/null +++ b/files/zh-tw/web/api/customevent/customevent/index.html @@ -0,0 +1,90 @@ +--- +title: CustomEvent() +slug: Web/API/CustomEvent/CustomEvent +translation_of: Web/API/CustomEvent/CustomEvent +--- +<p>{{APIRef("DOM")}}</p> + +<p><code><strong>CustomEvent()</strong></code> constructor 可用來建立 {{domxref("CustomEvent")}}.</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"> <em>event</em> = new CustomEvent(<em>typeArg</em>, <em>customEventInit</em>);</pre> + +<h3 id="參數">參數</h3> + +<dl> + <dt><em>typeArg</em></dt> + <dd>一個 {{domxref("DOMString")}} 用來表示事件名稱。</dd> + <dt><em>customEventInit</em>{{optional_inline}}</dt> + <dd>Is a <code>CustomEventInit</code> dictionary, having the following fields: + <ul> + <li><code>"detail"</code>, optional and defaulting to <code>null</code>, of type any, that is a event-dependant value associated with the event.</li> + </ul> + + <div class="note"> + <p><em>The <code>CustomEventInit</code></em><em> dictionary also accepts fields from the {{domxref("Event.Event", "EventInit")}} dictionary.</em></p> + </div> + </dd> +</dl> + +<h2 id="範例">範例</h2> + +<pre class="brush: js">// add an appropriate event listener +obj.addEventListener("cat", function(e) { process(e.detail) }); + +// create and dispatch the event +var event = new CustomEvent("cat", { + detail: { + hazcheeseburger: true + } +}); +obj.dispatchEvent(event);</pre> + +<h2 id="規格">規格</h2> + +<table class="standard-table" style="height: 49px; width: 1000px;"> + <thead> + <tr> + <th scope="col">Specification</th> + <th scope="col">Status</th> + <th scope="col">Comment</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{SpecName('DOM WHATWG','#interface-customevent','CustomEvent()')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器支援度">瀏覽器支援度</h2> + + + +<p>{{Compat("api.CustomEvent.CustomEvent")}}</p> + +<h2 id="添加額外參數">添加額外參數</h2> + +<p>在 Internet Explorer 9 或更高的版本，你可以用以下的方法給 <code>CustomEvent()</code> constructor 添加額外參數</p> + +<pre class="brush: js">(function () { + function CustomEvent ( event, params ) { + params = params || { bubbles: false, cancelable: false, detail: undefined }; + var evt = document.createEvent( 'CustomEvent' ); + evt.initCustomEvent( event, params.bubbles, params.cancelable, params.detail ); + return evt; + } + + CustomEvent.prototype = window.Event.prototype; + + window.CustomEvent = CustomEvent; +})();</pre> + +<h2 id="延伸閱讀">延伸閱讀</h2> + +<ul> + <li>{{domxref("CustomEvent")}}</li> +</ul> diff --git a/files/zh-tw/web/api/customevent/index.html b/files/zh-tw/web/api/customevent/index.html new file mode 100644 index 0000000000..e35df7df2e --- /dev/null +++ b/files/zh-tw/web/api/customevent/index.html @@ -0,0 +1,88 @@ +--- +title: CustomEvent +slug: Web/API/CustomEvent +tags: + - 待翻譯 +translation_of: Web/API/CustomEvent +--- +<p>{{APIRef("DOM")}}</p> + +<p><strong><code>CustomEvent</code></strong> interface 是應用程式為了任意目的所初始化的事件。</p> + +<h2 id="建構式">建構式</h2> + +<dl> + <dt>{{domxref("CustomEvent.CustomEvent", "CustomEvent()")}}</dt> + <dd>建立一個 <code>CustomEvent。</code></dd> +</dl> + +<h2 id="屬性">屬性</h2> + +<dl> + <dt>{{domxref("CustomEvent.detail")}} {{readonlyinline}}</dt> + <dd>初始化事件時傳送的任意資料。</dd> +</dl> + +<p><em>此介面繼承了其父介面 {{domxref("Event")}} 的屬性：</em></p> + +<p>{{Page("/zh-TW/docs/Web/API/Event", "屬性")}}</p> + +<h2 id="方法">方法</h2> + +<dl> + <dt>{{domxref("CustomEvent.initCustomEvent()")}} {{deprecated_inline}}</dt> + <dd> + <p>初始化一 <code>CustomEvent</code> object。若該事件已經被觸發，則不會進行任何動作。</p> + </dd> +</dl> + +<p><em>此介面繼承了其父介面 {{domxref("Event")}} 的方法：</em></p> + +<p>{{Page("/zh-TW/docs/Web/API/Event", "方法")}}</p> + +<h2 id="規格">規格</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('DOM WHATWG','#interface-customevent','CustomEvent')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>原始定義</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器兼容性">瀏覽器兼容性</h2> + + + +<p>{{Compat("api.CustomEvent")}}</p> + +<h2 id="Firing_from_privileged_code_to_non-privileged_code">Firing from privileged code to non-privileged code</h2> + +<p>當要從 privileged code （像是插件）到非 privileged code （例如網頁）執行 CustomEvent ，你必須要考慮這之間的安全性。Firefox 和其他 Gecko 應用會對此有所限制。雖然這可以自動防止安全漏洞發生，但也可能導致您的程式碼沒辦法正常執行。</p> + +<p>When creating a CustomEvent object, you must create the object from the same <a href="/en-US/docs/XUL/window">window</a> as you're going to fire against. The <code>detail</code> attribute of your CustomEvent will be subject to the same restrictions. String and Array values will be readable by the content without restrictions, but custom Objects will not. If using a custom Object, you will need to define the attributes of that object that are readable from the content script using <a href="/en-US/docs/">Components.utils.cloneInto()</a>.</p> + +<pre class="brush: js">// doc is a reference to the content document +function dispatchCustomEvent(doc) { + var eventDetail = Components.utils.cloneInto({foo: 'bar'}, doc.defaultView); + var myEvent = doc.defaultView.CustomEvent("mytype", eventDetail); + doc.dispatchEvent(myEvent); +}</pre> + +<p>Note that exposing a function will allow the content script to run it with chrome privileges, which can open a security vulnerability.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/en-US/docs/Code_snippets/Interaction_between_privileged_and_non-privileged_pages" title="/en-US/docs/Code_snippets/Interaction_between_privileged_and_non-privileged_pages">Interaction between privileged and non-privileged pages</a></li> + <li><a href="/en-US/docs/Web/API/window.postMessage" title="/en-US/docs/Web/API/window.postMessage">Window.postMessage</a></li> +</ul> diff --git a/files/zh-tw/web/api/datatransfer/index.html b/files/zh-tw/web/api/datatransfer/index.html new file mode 100644 index 0000000000..d202c3b876 --- /dev/null +++ b/files/zh-tw/web/api/datatransfer/index.html @@ -0,0 +1,204 @@ +--- +title: DataTransfer +slug: Web/API/DataTransfer +translation_of: Web/API/DataTransfer +--- +<div>{{APIRef("HTML Drag and Drop API")}}</div> + +<p><code><strong>DataTransfer</strong></code> 物件被用來保存使用者於拖放操作過程中的資料，其中可能包含了一至多項資料以及多種資料類型。要瞭解拖放操作的更多細節，請參考<a href="/zh-TW/docs/Web/API/HTML_Drag_and_Drop_API">拖放操作</a>一文。</p> + +<p><code>DataTransfer</code> 只能是每一種 {{domxref("DragEvent")}} 型別物件的共同屬性－{{domxref("DragEvent.dataTransfer","dataTransfer")}}，不能夠被單獨建立。</p> + +<h2 id="屬性">屬性</h2> + +<h3 id="Standard_properties">Standard properties</h3> + +<dl> + <dt>{{domxref("DataTransfer.dropEffect")}}</dt> + <dd>Gets the type of drag-and-drop operation currently selected or sets the operation to a new type. The value must be <code>none</code> <code>copy</code> <code>link</code> or <code>move</code>.</dd> + <dt>{{domxref("DataTransfer.effectAllowed")}}</dt> + <dd>Provides all of the types of operations that are possible. Must be one of <code>none</code>, <code>copy</code>, <code>copyLink</code>, <code>copyMove</code>, <code>link</code>, <code>linkMove</code>, <code>move</code>, <code>all</code> or <code>uninitialized</code>.</dd> + <dt>{{domxref("DataTransfer.files")}}</dt> + <dd>Contains a list of all the local files available on the data transfer. If the drag operation doesn't involve dragging files, this property is an empty list.</dd> + <dt>{{domxref("DataTransfer.items")}} {{readonlyInline}}</dt> + <dd>Gives a {{domxref("DataTransferItemList")}} object which is a list of all of the drag data.</dd> + <dt>{{domxref("DataTransfer.types")}} {{readonlyInline}}</dt> + <dd>An array of {{domxref("DOMString","strings")}} giving the formats that were set in the {{event("dragstart")}} event.</dd> +</dl> + +<h3 id="Gecko_properties">Gecko properties</h3> + +<p>{{SeeCompatTable}}</p> + +<div class="note"><strong>Note:</strong> All of the properties in this section are Gecko-specific.</div> + +<dl> + <dt>{{domxref("DataTransfer.mozCursor")}}</dt> + <dd>Gives the drag cursor's state. This is primarily used to control the cursor during tab drags.</dd> + <dt>{{domxref("DataTransfer.mozItemCount")}} {{readonlyInline}}</dt> + <dd>Gives the number of items in the drag operation.</dd> + <dt>{{domxref("DataTransfer.mozSourceNode")}} {{readonlyInline}}</dt> + <dd>The {{ domxref("Node") }} over which the mouse cursor was located when the button was pressed to initiate the drag operation. This value is <code>null</code> for external drags or if the caller can't access the node.</dd> + <dt>{{domxref("DataTransfer.mozUserCancelled")}} {{readonlyInline}}</dt> + <dd>This property applies only to the <code>dragend</code> event, and is <code>true</code> if the user canceled the drag operation by pressing escape. It will be <code>false</code> in all other cases, including if the drag failed for any other reason, for instance due to a drop over an invalid location.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<h3 id="Standard_methods">Standard methods</h3> + +<dl> + <dt>{{domxref("DataTransfer.clearData()")}}</dt> + <dd>Remove the data associated with a given type. The type argument is optional. If the type is empty or not specified, the data associated with all types is removed. If data for the specified type does not exist, or the data transfer contains no data, this method will have no effect.</dd> + <dt>{{domxref("DataTransfer.getData()")}}</dt> + <dd>Retrieves the data for a given type, or an empty string if data for that type does not exist or the data transfer contains no data.</dd> + <dt>{{domxref("DataTransfer.setData()")}}</dt> + <dd>Set the data for a given type. If data for the type does not exist, it is added at the end, such that the last item in the types list will be the new format. If data for the type already exists, the existing data is replaced in the same position.</dd> + <dt>{{domxref("DataTransfer.setDragImage()")}}</dt> + <dd>Set the image to be used for dragging if a custom one is desired.</dd> +</dl> + +<h3 id="Gecko_methods">Gecko methods</h3> + +<p>{{SeeCompatTable}}</p> + +<div class="note"><strong>Note:</strong> All of the methods in this section are Gecko-specific.</div> + +<dl> + <dt>{{domxref("DataTransfer.addElement()")}}</dt> + <dd>Sets the drag source to the given element.</dd> + <dt>{{domxref("DataTransfer.mozClearDataAt()")}}</dt> + <dd>Removes the data associated with the given format for an item at the specified index. The index is in the range from zero to the number of items minus one.</dd> + <dt>{{domxref("DataTransfer.mozGetDataAt()")}}</dt> + <dd>Retrieves the data associated with the given format for an item at the specified index, or null if it does not exist. The index should be in the range from zero to the number of items minus one.</dd> + <dt>{{domxref("DataTransfer.mozSetDataAt()")}}</dt> + <dd>A data transfer may store multiple items, each at a given zero-based index. <code>mozSetDataAt()</code> may only be called with an index argument less than <code>mozItemCount</code> in which case an existing item is modified, or equal to <code>mozItemCount</code> in which case a new item is added, and the <code>mozItemCount</code> is incremented by one.</dd> + <dt>{{domxref("DataTransfer.mozTypesAt()")}}</dt> + <dd>Holds a list of the format types of the data that is stored for an item at the specified index. If the index is not in the range from 0 to the number of items minus one, an empty string list is returned.</dd> +</dl> + +<h2 id="範例">範例</h2> + +<p>Every method and property listed in this document has its own reference page and each reference page either directly includes an example of the interface or has a link to an example.</p> + +<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('HTML WHATWG', 'interaction.html#datatransfer','DataTransfer')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td><code>mozCursor</code>, <code>mozItemCount</code>, <code>mozSourceNode</code>, <code>mozUserCancelled</code>, <code>addElement()</code>, <code>mozClearDataAt()</code>, <code>mozGetDataAt()</code>, <code>mozSetDataAt()</code> and <code>mozTypesAt</code> are Gecko specific.</td> + </tr> + <tr> + <td>{{SpecName('HTML5.1', 'editing.html#the-datatransfer-interface','DataTransfer')}}</td> + <td>{{Spec2('HTML5.1')}}</td> + <td>Not included in W3C HTML5 {{Spec2('HTML5 W3C')}}</td> + </tr> + <tr> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>4</td> + <td>{{CompatVersionUnknown}}</td> + <td>3.5 <sup>[2]</sup><br> + {{CompatGeckoDesktop(52)}}<sup>[3]</sup></td> + <td>10 <sup>[1]</sup> <sup>[2]</sup></td> + <td>12</td> + <td>3.1 <sup>[2]</sup></td> + </tr> + <tr> + <td>{{domxref("DataTransfer.items", "items")}} property</td> + <td>4</td> + <td>{{CompatVersionUnknown}}</td> + <td>50</td> + <td>{{CompatNo}}</td> + <td>12</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>Chrome for Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}<br> + {{CompatGeckoMobile(52)}}<sup>[3]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatIE("10")}}[1][2]</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>{{domxref("DataTransfer.items", "items")}} property</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile(50)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] <a href="http://caniuse.com/#search=drag">Partial support refers to not supporting {{domxref("DataTransfer.setDragImage()")}} [CanIUse.com].</a></p> + +<p>[2] Does not support {{domxref("DataTransfer.items")}} property.</p> + +<p>[3] As of Firefox 52, the {{domxref("DataTransfer.types")}} property returns a frozen array of {{domxref("DOMString")}}s as per spec, rather than a {{domxref("DOMStringList")}}.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/Web/Guide/HTML/Drag_and_drop">Drag and drop</a></li> + <li><a href="/Web/Guide/HTML/Drag_operations">Drag Operations</a></li> + <li><a href="/Web/Guide/HTML/Recommended_Drag_Types">Recommended Drag Types</a></li> + <li><a href="/Web/Guide/HTML/Dragging_and_Dropping_Multiple_Items">Dragging and Dropping Multiple Items</a></li> +</ul> diff --git a/files/zh-tw/web/api/detecting_device_orientation/index.html b/files/zh-tw/web/api/detecting_device_orientation/index.html new file mode 100644 index 0000000000..d81307ba57 --- /dev/null +++ b/files/zh-tw/web/api/detecting_device_orientation/index.html @@ -0,0 +1,278 @@ +--- +title: 偵測裝置方向 +slug: Web/API/Detecting_device_orientation +translation_of: Web/API/Detecting_device_orientation +--- +<div>{{SeeCompatTable}}</div> + +<p>目前支援 Web 的裝置，已有越來越多可偵測本身的方向（<strong>Orientation</strong>）；也就是說，這些裝置可根據重力牽引的相對關係而改變其畫面方向，同時回報該筆資料。特別是如行動電話的手持式裝置，同樣會判斷這種資訊而自動旋轉其畫面。如此除了能保持正向畫面之外，裝置橫放時亦能以寬螢幕呈現網頁內容。</p> + +<p>現有 2 組 JavaScript 事件可處理方向資訊。第一個是 {{domxref("DeviceOrientationEvent")}} 事件。只要加速規偵測到裝置方向的變化，隨即送出此事件。在接收並處理這些方向事件所回報的資料之後，即可針對使用者移動裝置所造成的方向與高度變化，確實做出回應。</p> + +<p>第二個為 {{domxref("DeviceMotionEvent")}} 事件。只要加速過程產生變化，隨即送出該事件。此事件用以監聽加速過程的變化，因此不同於 {{domxref("DeviceOrientationEvent")}} 的方向變化。如筆記型電腦中的感測器，一般均能夠偵測 {{domxref("DeviceMotionEvent")}} 而保護移動中的儲存裝置。{{domxref("DeviceOrientationEvent")}} 則較常用於行動裝置。</p> + +<h2 id="處理方向事件">處理方向事件</h2> + +<p>若要開始接收方向變換的情形，只要監聽 {{event("deviceorientation")}} 事件即可：</p> + +<div class="note"> +<p><strong>Note</strong>: <a href="https://github.com/dorukeker/gyronorm.js">gyronorm.js</a> is a polyfill for normalizing the accelerometer and gyroscope data on mobile devices. This is useful for overcoming some of the differences in device support for device orientation.</p> +</div> + +<pre class="brush: js">window.addEventListener("deviceorientation", handleOrientation, true); +</pre> + +<p>在註冊了事件監聽器（Event listener。本範例使用 <code>handleOrientation()</code> 函式）之後，將以更新過的方向資料而定期呼叫你的監聽器函式。</p> + +<p>方向事件共有 4 組值：</p> + +<ul> + <li>{{ domxref("DeviceOrientationEvent.absolute") }}</li> + <li>{{ domxref("DeviceOrientationEvent.alpha") }}</li> + <li>{{ domxref("DeviceOrientationEvent.beta") }}</li> + <li>{{ domxref("DeviceOrientationEvent.gamma") }}</li> +</ul> + +<p>事件處理器（Event handler）函式則如下列：</p> + +<pre class="brush: js">function handleOrientation(event) { + var absolute = event.absolute; + var alpha = event.alpha; + var beta = event.beta; + var gamma = event.gamma; + + // Do stuff with the new orientation data +} +</pre> + +<h3 id="方向值說明">方向值說明</h3> + +<p>所回報的各個軸線值，均是以標準座標而呈現對應各軸線的旋轉量 (Amount of rotation)。可參閱下方所提供的<a href="/DOM/Orientation_and_motion_data_explained" title="Orientation and motion data explained">方向與動向資料說明</a>文章以獲得詳細資訊。</p> + +<ul> + <li>{{domxref("DeviceOrientationEvent.alpha")}} 值為裝置的 z 軸動向 (Motion)，介於 0 ~ 360 度之間。</li> + <li>{{domxref("DeviceOrientationEvent.beta")}} 值為裝置的 x 軸動向，介於 -180 ~ 180 度之間，代表裝置的前後動向。</li> + <li>{{domxref("DeviceOrientationEvent.gamma")}} 值為裝置的 y 軸動向，介於 -90 ~ 90 度之間，代表裝置的左右動向。</li> +</ul> + +<h3 id="方向範例">方向範例</h3> + +<p>只要瀏覽器支援 {{event("deviceorientation")}} 事件，且該執行裝置可偵測自己的方向，均可使用此範例。</p> + +<p>先想像花園裡有 1 顆球：</p> + +<pre class="brush: html"><div class="garden"> + <div class="ball"></div> +</div> + +<pre class="output"></pre> +</pre> + +<p>這座花園為 200 像素寬（對，一座小花園），球就位在正中央：</p> + +<pre class="brush: css">.garden { + position: relative; + width : 200px; + height: 200px; + border: 5px solid #CCC; + border-radius: 10px; +} + +.ball { + position: absolute; + top : 90px; + left : 90px; + width : 20px; + height: 20px; + background: green; + border-radius: 100%; +} +</pre> + +<p>現在只要移動裝置，球也會跟著移動：</p> + +<pre class="brush: js">var ball = document.querySelector('.ball'); +var garden = document.querySelector('.garden'); +var output = document.querySelector('.output'); + +var maxX = garden.clientWidth - ball.clientWidth; +var maxY = garden.clientHeight - ball.clientHeight; + +function handleOrientation(event) { + var x = event.beta; // In degree in the range [-180,180] + var y = event.gamma; // In degree in the range [-90,90] + + output.innerHTML = "beta : " + x + "\n"; + output.innerHTML += "gamma: " + y + "\n"; + + // Because we don't want to have the device upside down + // We constrain the x value to the range [-90,90] + if (x > 90) { x = 90}; + if (x < -90) { x = -90}; + + // To make computation easier we shift the range of + // x and y to [0,180] + x += 90; + y += 90; + + // 10 is half the size of the ball + // It center the positioning point to the center of the ball + ball.style.top = (maxX*x/180 - 10) + "px"; + ball.style.left = (maxY*y/180 - 10) + "px"; +} + +window.addEventListener('deviceorientation', handleOrientation); +</pre> + +<p>這裡有即時結果 (若無法顯示，可至本文右上角切換回英文原文觀看)：</p> + +<div>{{EmbedLiveSample('Orientation_example', '230', '260')}}</div> + +<div class="warning"> +<p><strong>警告：</strong>Chrome 與 Firefox 處理角度的方式不同，所以某些軸線可能方向顛倒。</p> +</div> + +<h2 id="處理動向事件">處理動向事件</h2> + +<p>動向事件與方向事件的處理方式完全相同，但動向事件擁有自己的名稱：{{event("devicemotion")}}</p> + +<pre class="brush: js">window.addEventListener("devicemotion", <em>handleMotion</em>, true);</pre> + +<p>真正改變的是由 {{domxref("DeviceMotionEvent")}} 物件所提供的資訊；且該物件又作為 <em>HandleMotion</em> 函式的參數。</p> + +<p>動向事件共有 4 組屬性：</p> + +<ul> + <li>{{ domxref("DeviceMotionEvent.acceleration") }}</li> + <li>{{ domxref("DeviceMotionEvent.accelerationIncludingGravity") }}</li> + <li>{{ domxref("DeviceMotionEvent.rotationRate") }}</li> + <li>{{ domxref("DeviceMotionEvent.interval") }}</li> +</ul> + +<h3 id="動向值說明">動向值說明</h3> + +<p>{{domxref("DeviceMotionEvent")}} 物件將提供「裝置位置與方向的變化速度」的相關資訊，並根據 3 組軸線 (可參閱<a href="/docs/Web/Guide/DOM/Events/Orientation_and_motion_data_explained" title="/en-US/docs/Web/Guide/DOM/Events/Orientation_and_motion_data_explained">方向與動向資料說明</a>的細節) 提供變化情形。</p> + +<p>針對 {{domxref("DeviceMotionEvent.acceleration","acceleration")}} 與 {{domxref("DeviceMotionEvent.accelerationIncludingGravity","accelerationIncludingGravity")}}，這些軸線將對應：</p> + +<ul> + <li><code>x</code><code>：代表由東至西的軸線</code></li> + <li><code>y</code><code>：代表由南至北的軸線</code></li> + <li><code>z</code><code>：代表與地面垂直的軸線</code></li> +</ul> + +<p>針對稍有差異的 {{domxref("DeviceMotionEvent.rotationRate","rotationRate")}}，則資訊將對應：</p> + +<ul> + <li><code>alpha</code><code>：代表與螢幕 </code>(或桌機的鍵盤) <code>垂直的軸線之旋轉率</code></li> + <li><code>beta</code><code>：代表與螢幕平面 </code>(或桌機的鍵盤) 由左至右軸線之旋轉率</li> + <li><code>gamma</code><code>：代表與螢幕平面 </code>(或桌機的鍵盤) 由下至上軸線之旋轉率</li> +</ul> + +<p>最後，{{domxref("DeviceMotionEvent.interval","interval")}} 代表以毫秒（Millisecond）為單位的時間間隔，是裝置取得資料的頻率。</p> + +<h2 id="規範">規範</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('Device Orientation')}}</td> + <td>{{Spec2('Device Orientation')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>{{domxref("DeviceOrientationEvent")}}</td> + <td>7.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>3.6<sup>[1]</sup><br> + 6</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>{{domxref("DeviceMotionEvent")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>6</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>{{domxref("DeviceOrientationEvent")}}</td> + <td>3.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>3.6<sup>[1]</sup><br> + 6</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>4.2</td> + </tr> + <tr> + <td>{{domxref("DeviceMotionEvent")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>6</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Firefox 3.6 to 5 supported <a href="/en-US/docs/Web/Events/MozOrientation">mozOrientation</a> versus the standard {{domxref("DeviceOrientationEvent")}} event.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("DeviceOrientationEvent")}}</li> + <li>{{domxref("DeviceMotionEvent")}}</li> + <li>舊版 <a href="/docs/Web/Events/MozOrientation" title="en-US/DOM/MozOrientation">MozOrientation</a> 事件</li> + <li><a href="/docs/Web/Guide/DOM/Events/Orientation_and_motion_data_explained" title="Orientation and motion data explained">方向與動向資料說明</a></li> + <li><a href="/docs/Web/Guide/DOM/Events/Using_device_orientation_with_3D_transforms" title="Using Deviceorientation In 3D Transforms">於 3D Transforms 中使用 deviceorientation</a></li> + <li><a href="/docs/Games/Workflows/HTML5_Gamedev_Phaser_Device_Orientation">Cyber Orb: 2D maze game with device orientation</a></li> +</ul> diff --git a/files/zh-tw/web/api/devicemotionevent/index.html b/files/zh-tw/web/api/devicemotionevent/index.html new file mode 100644 index 0000000000..f21723a1e3 --- /dev/null +++ b/files/zh-tw/web/api/devicemotionevent/index.html @@ -0,0 +1,116 @@ +--- +title: DeviceMotionEvent +slug: Web/API/DeviceMotionEvent +translation_of: Web/API/DeviceMotionEvent +--- +<p>{{apiref("Device Orientation Events")}}{{SeeCompatTable}}</p> + +<h2 id="概要">概要</h2> + +<p><code>DeviceMotionEvent</code> 提供了網頁開發者關於裝置位置及旋轉方向改變時的速度資訊。</p> + +<div class="warning"> +<p><strong>Warning:</strong> Currently, Firefox and Chrome does not handle the coordinates the same way. Take care about this while using them.</p> +</div> + +<h2 id="屬性">屬性</h2> + +<dl> + <dt>{{domxref("DeviceMotionEvent.acceleration")}} {{readonlyinline}}</dt> + <dd>An object giving the acceleration of the device on the three axis X, Y and Z. Acceleration is expressed in <a href="https://en.wikipedia.org/wiki/Meter_per_second_squared" title="https://en.wikipedia.org/wiki/Meter_per_second_squared">m/s<sup>2</sup></a>.</dd> + <dt>{{domxref("DeviceMotionEvent.accelerationIncludingGravity")}} {{readonlyinline}}</dt> + <dd>An object giving the acceleration of the device on the three axis X, Y and Z with the effect of gravity. Acceleration is expressed in <a href="https://en.wikipedia.org/wiki/Meter_per_second_squared" title="https://en.wikipedia.org/wiki/Meter_per_second_squared">m/s<sup>2</sup></a>.</dd> + <dt>{{domxref("DeviceMotionEvent.rotationRate")}} {{readonlyinline}}</dt> + <dd>An object giving the rate of change of the device's orientation on the three orientation axis alpha, beta and gamma. Rotation rate is express in degrees per seconds.</dd> + <dt>{{domxref("DeviceMotionEvent.interval")}} {{readonlyinline}}</dt> + <dd>A number representing the interval of time, in milliseconds, at which data is obtained from the device.</dd> +</dl> + +<h2 id="範例">範例</h2> + +<pre class="brush: js">window.addEventListener('devicemotion', function(event) { + console.log(event.acceleration.x + ' m/s2'); +});</pre> + +<h2 id="規範">規範</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('Device Orientation')}}</td> + <td>{{Spec2('Device Orientation')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("6")}}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("6")}}</td> + <td>{{ CompatNo() }}</td> + <td>{{ CompatNo() }}</td> + <td>4.2</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{ event("deviceorientation") }}</li> + <li>{{ domxref("DeviceMotionEvent") }}</li> + <li>{{ event("devicemotion") }}</li> + <li><a href="/en-US/docs/WebAPI/Detecting_device_orientation" title="/en-US/docs/WebAPI/Detecting_device_orientation">Detecting device orientation</a></li> + <li><a href="https://developer.mozilla.org/en/DOM/Orientation_and_motion_data_explained" title="Orientation and motion data explained">Orientation and motion data explained</a></li> +</ul> diff --git a/files/zh-tw/web/api/deviceorientationevent/index.html b/files/zh-tw/web/api/deviceorientationevent/index.html new file mode 100644 index 0000000000..38bc8f5261 --- /dev/null +++ b/files/zh-tw/web/api/deviceorientationevent/index.html @@ -0,0 +1,122 @@ +--- +title: DeviceOrientationEvent +slug: Web/API/DeviceOrientationEvent +translation_of: Web/API/DeviceOrientationEvent +--- +<p>{{apiref("Device Orientation Events")}}{{SeeCompatTable}}</p> + +<p><code>DeviceOrientationEvent</code> 提供了網頁開發者關於目前瀏覽頁面之裝置的物理旋轉方向資訊。</p> + +<div class="warning"> +<p><strong>Warning:</strong> Currently, Firefox and Chrome do not handle the coordinates the same way. Take care about this while using them.</p> +</div> + +<h2 id="屬性">屬性</h2> + +<dl> + <dt>{{domxref("DeviceOrientationEvent.absolute")}} {{readonlyinline}}</dt> + <dd>A boolean that indicates whether or not the device is providing orientation data absolutely.</dd> + <dt>{{domxref("DeviceOrientationEvent.alpha")}} {{readonlyinline}}</dt> + <dd>A number representing the motion of the device around the z axis, express in degrees with values ranging from 0 to 360</dd> + <dt>{{domxref("DeviceOrientationEvent.beta")}} {{readonlyinline}}</dt> + <dd>A number representing the motion of the device around the x axis, express in degrees with values ranging from -180 to 180. This represents a front to back motion of the device.</dd> + <dt>{{domxref("DeviceOrientationEvent.gamma")}} {{readonlyinline}}</dt> + <dd>A number representing the motion of the device around the y axis, express in degrees with values ranging from -90 to 90. This represents a left to right motion of the device.</dd> +</dl> + +<h2 id="範例">範例</h2> + +<pre class="brush: js">window.addEventListener('deviceorientation', function(event) { + console.log(event.alpha + ' : ' + event.beta + ' : ' + event.gamma); +});</pre> + +<h2 id="規範">規範</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('Device Orientation')}}</td> + <td>{{Spec2('Device Orientation')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>7.0 [1]</td> + <td>{{CompatVersionUnknown}}</td> + <td>6 [2]</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</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>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</td> + <td>{{CompatVersionUnknown}} [1]</td> + <td>{{CompatVersionUnknown}}</td> + <td>6 [2]</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>4.2</td> + <td>{{CompatVersionUnknown}} [1]</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Before version 50, Chrome provided absolute values instead of relative values for this event. Developers still needing absolute values may use the {{domxref("ondeviceorientationabsolute")}} event.</p> + +<p>[2] Firefox 3.6, 4, and 5 supported <a href="/en-US/DOM/MozOrientation">mozOrientation </a>instead of the standard <code>DeviceOrientationEvent</code> interface</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{ event("deviceorientation") }}</li> + <li>{{ domxref("DeviceMotionEvent") }}</li> + <li>{{ event("devicemotion") }}</li> + <li><a href="/en-US/docs/WebAPI/Detecting_device_orientation" title="/en-US/docs/WebAPI/Detecting_device_orientation">Detecting device orientation</a></li> + <li><a href="https://developer.mozilla.org/en/DOM/Orientation_and_motion_data_explained" title="Orientation and motion data explained">Orientation and motion data explained</a></li> +</ul> diff --git a/files/zh-tw/web/api/document.createtreewalker/index.html b/files/zh-tw/web/api/document.createtreewalker/index.html new file mode 100644 index 0000000000..9e74411a14 --- /dev/null +++ b/files/zh-tw/web/api/document.createtreewalker/index.html @@ -0,0 +1,224 @@ +--- +title: Document.createTreeWalker() +slug: Web/API/document.createTreeWalker +translation_of: Web/API/Document/createTreeWalker +--- +<div> + {{ApiRef("Document")}}</div> +<p><strong><code>Document.createTreeWalker()</code></strong> 方法，能建立一個 {{domxref("TreeWalker")}} 物件並傳回.</p> +<h2 id="Syntax" name="Syntax">語法</h2> +<pre class="syntaxbox"><em>treeWalker</em> = <em>document</em>.createTreeWalker(<em>root</em>, <em>whatToShow</em>, <em>filter</em>, <em>entityReferenceExpansion</em>); +</pre> +<h3 id="參數">參數</h3> +<dl> + <dt> + <em>root </em></dt> + <dd> + 是這個 {{domxref("TreeWalker")}} 遍歷的根節點(root {{domxref("Node")}}). Typically this will be an element owned by the document.</dd> + <dt> + <em>whatToShow {{optional_inline}}</em></dt> + <dd> + Is an optional <code>unsigned long</code> representing a bitmask created by combining the constant properties of <code><a href="http://www.w3.org/TR/DOM-Level-2-Traversal-Range/traversal.html#Traversal-NodeFilter" title="http://www.w3.org/TR/DOM-Level-2-Traversal-Range/traversal.html#Traversal-NodeFilter">NodeFilter</a></code>. 它是一種方便的方法，用來過濾某些類型的節點。 It defaults to <code>0xFFFFFFFF</code> representing the <code>SHOW_ALL</code> constant.<br> + <table class="standard-table"> + <tbody> + <tr> + <td class="header">Constant</td> + <td class="header">數值</td> + <td class="header">說明</td> + </tr> + <tr> + <td><code>NodeFilter.SHOW_ALL</code></td> + <td><code>-1</code> (that is the max value of <code>unsigned long</code>)</td> + <td>顯示所有節點.</td> + </tr> + <tr> + <td><code><code>NodeFilter.</code>SHOW_ATTRIBUTE</code> {{deprecated_inline}}</td> + <td><code>2</code></td> + <td>Shows attribute {{ domxref("Attr") }} nodes. This is meaningful only when creating a {{ domxref("TreeWalker") }} with an {{ domxref("Attr") }} node as its root; in this case, it means that the attribute node will appear in the first position of the iteration or traversal. Since attributes are never children of other nodes, they do not appear when traversing over the document tree.</td> + </tr> + <tr> + <td><code><code>NodeFilter.</code>SHOW_CDATA_SECTION</code> {{deprecated_inline}}</td> + <td><code>8</code></td> + <td>Shows {{ domxref("CDATASection") }} nodes.</td> + </tr> + <tr> + <td><code><code>NodeFilter.</code>SHOW_COMMENT</code></td> + <td><code>128</code></td> + <td>Shows {{ domxref("Comment") }} nodes.</td> + </tr> + <tr> + <td><code><code>NodeFilter.</code>SHOW_DOCUMENT</code></td> + <td><code>256</code></td> + <td>Shows {{ domxref("Document") }} nodes.</td> + </tr> + <tr> + <td><code><code>NodeFilter.</code>SHOW_DOCUMENT_FRAGMENT</code></td> + <td><code>1024</code></td> + <td>Shows {{ domxref("DocumentFragment") }} nodes.</td> + </tr> + <tr> + <td><code><code>NodeFilter.</code>SHOW_DOCUMENT_TYPE</code></td> + <td><code>512</code></td> + <td>Shows {{ domxref("DocumentType") }} nodes.</td> + </tr> + <tr> + <td><code><code>NodeFilter.</code>SHOW_ELEMENT</code></td> + <td><code>1</code></td> + <td>Shows {{ domxref("Element") }} nodes.</td> + </tr> + <tr> + <td><code><code>NodeFilter.</code>SHOW_ENTITY</code> {{deprecated_inline}}</td> + <td><code>32</code></td> + <td>Shows {{ domxref("Entity") }} nodes. This is meaningful only when creating a {{ domxref("TreeWalker") }} with an {{ domxref("Entity") }} node as its root; in this case, it means that the {{ domxref("Entity") }} node will appear in the first position of the traversal. Since entities are not part of the document tree, they do not appear when traversing over the document tree.</td> + </tr> + <tr> + <td><code><code>NodeFilter.</code>SHOW_ENTITY_REFERENCE</code> {{deprecated_inline}}</td> + <td><code>16</code></td> + <td>Shows {{ domxref("EntityReference") }} nodes.</td> + </tr> + <tr> + <td><code><code><code>NodeFilter.</code></code>SHOW_NOTATION</code> {{deprecated_inline}}</td> + <td><code>2048</code></td> + <td>Shows {{ domxref("Notation") }} nodes. This is meaningful only when creating a {{ domxref("TreeWalker") }} with a {{ domxref("Notation") }} node as its root; in this case, it means that the {{ domxref("Notation") }} node will appear in the first position of the traversal. Since entities are not part of the document tree, they do not appear when traversing over the document tree.</td> + </tr> + <tr> + <td><code><code>NodeFilter.</code>SHOW_PROCESSING_INSTRUCTION</code></td> + <td><code>64</code></td> + <td>Shows {{ domxref("ProcessingInstruction") }} nodes.</td> + </tr> + <tr> + <td><code><code>NodeFilter.</code>SHOW_TEXT</code></td> + <td><code>4</code></td> + <td>顯示文字節點({{ domxref("Text") }} nodes).</td> + </tr> + </tbody> + </table> + </dd> + <dt> + <em>filter <em>{{optional_inline}}</em></em></dt> + <dd> + 是一個可選的 {{domxref("NodeFilter")}}, 這是一個物件有著 <code>acceptNode</code> 方法, 這方法被 {{domxref("TreeWalker")}} 呼叫來決定是否接受通過 <code>whatToShow</code> 檢查的節點.</dd> + <dt> + <em>entityReferenceExpansion<em> {{optional_inline}}</em></em> <em>{{obsolete_inline}}</em></dt> + <dd> + Is a {{domxref("Boolean")}} flag indicating if when discarding an {{domxref("EntityReference")}} its whole sub-tree must be discarded at the same time.</dd> +</dl> +<h2 id="Example" name="Example">Example</h2> +<p>The following example goes through all nodes in the body, reduces the set of nodes to elements, simply passes through as acceptable each node (it could reduce the set in the <code>acceptNode()</code> method instead), and then makes use of tree walker iterator that is created to advance through the nodes (now all elements) and push them into an array.</p> +<pre class="brush: js">var treeWalker = document.createTreeWalker( + document.body, + NodeFilter.SHOW_ELEMENT, + { acceptNode: function(node) { return NodeFilter.FILTER_ACCEPT; } }, + false +); + +var nodeList = []; + +while(treeWalker.nextNode()) nodeList.push(treeWalker.currentNode); +</pre> +<h2 id="Specification" name="Specification">Specifications</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('DOM WHATWG', '#dom-document-createtreewalker', 'Document.createTreeWalker')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>Removed the <code>expandEntityReferences</code> parameter.<br> + Made the <code>whatToShow</code> and <code>filter</code> parameters optionals.</td> + </tr> + <tr> + <td>{{SpecName('DOM2 Traversal_Range', 'traversal.html#NodeIteratorFactory-createTreeWalker', 'Document.createTreeWalker')}}</td> + <td>{{Spec2('DOM2 Traversal_Range')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> +<h2 id="Browser_compatibility">Browser compatibility</h2> +<p>{{CompatibilityTable}}</p> +<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>1.0</td> + <td>{{CompatGeckoDesktop("1.8.1")}}</td> + <td>9.0</td> + <td>9.0</td> + <td>3.0</td> + </tr> + <tr> + <td><code>whatToShow</code> and <code>filter</code> optional</td> + <td>1.0</td> + <td>{{CompatGeckoDesktop("12")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>3.0</td> + </tr> + <tr> + <td><code>expandEntityReferences</code> {{obsolete_inline}}</td> + <td>1.0</td> + <td>{{CompatGeckoDesktop("1.8.1")}}<br> + Removed in {{CompatGeckoDesktop("12")}}</td> + <td>9.0</td> + <td>9.0</td> + <td>3.0</td> + </tr> + </tbody> + </table> +</div> +<div id="compat-mobile"> + <table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("1.8.1")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>9.0</td> + <td>3.0</td> + </tr> + <tr> + <td><code>whatToShow</code> and <code>filter</code> optional</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("12")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>3.0</td> + </tr> + <tr> + <td><code>expandEntityReferences</code> {{obsolete_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1.8.1")}}<br> + Removed in {{CompatGeckoDesktop("12")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>9.0</td> + <td>3.0</td> + </tr> + </tbody> + </table> +</div> +<h2 id="See_also">See also</h2> +<ul> + <li>The interface of the object it creates: {{domxref("TreeWalker")}}.</li> + <li><a href="http://msdn.microsoft.com/en-us/library/ie/ff975302(v=vs.85).aspx" title="http://msdn.microsoft.com/en-us/library/ie/ff975302(v=vs.85).aspx">createTreeWalker on MSDN</a></li> +</ul> diff --git a/files/zh-tw/web/api/document/body/index.html b/files/zh-tw/web/api/document/body/index.html new file mode 100644 index 0000000000..a33d2a7901 --- /dev/null +++ b/files/zh-tw/web/api/document/body/index.html @@ -0,0 +1,128 @@ +--- +title: Document.body +slug: Web/API/Document/body +translation_of: Web/API/Document/body +--- +<div>{{APIRef("DOM")}}</div> + +<p>回傳目前文件的 {{HTMLElement("body")}} 或 {{HTMLElement("frameset")}} 節點，如元素不存在則回傳 <code>null</code>。</p> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox"><em>var objRef</em> = document.body; +document.body = <em>objRef;</em></pre> + +<h2 id="Example" name="Example">範例</h2> + +<pre class="brush:js">// in HTML: <body id="oldBodyElement"></body> +alert(document.body.id); // "oldBodyElement" + +var aNewBodyElement = document.createElement("body"); + +aNewBodyElement.id = "newBodyElement"; +document.body = aNewBodyElement; +alert(document.body.id); // "newBodyElement" +</pre> + +<h2 id="Notes" name="Notes">備註</h2> + +<p><code>document.body</code> is the element that contains the content for the document. In documents with <code><body></code> contents, returns the <code><body></code> element, and in frameset documents, this returns the outermost <code><frameset></code> element.</p> + +<p>Though <code>body</code> is settable, setting a new body on a document will effectively remove all the current children of the existing <code><body></code> element.</p> + +<h2 id="Specification" name="Specification">規範</h2> + +<table class="spectable standard-table"> + <tbody> + <tr> + <th scope="col">Specification</th> + <th scope="col">Status</th> + <th scope="col">Comment</th> + </tr> + <tr> + <td>{{SpecName('HTML WHATWG','dom.html#dom-document-body','Document.body')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('HTML5.1','dom.html#dom-document-body','Document.body')}}</td> + <td>{{Spec2('HTML5.1')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C','dom.html#dom-document-body','Document.body')}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM2 HTML','html.html#ID-56360201','Document.body')}}</td> + <td>{{Spec2('DOM2 HTML')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM1','level-one-html.html#attribute-body','Document.body')}}</td> + <td>{{Spec2('DOM1')}}</td> + <td>Initial definition.</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>1</td> + <td>{{CompatVersionUnknown}}</td> + <td>2</td> + <td>6</td> + <td>9.6 (possibly earlier)</td> + <td>4 (possibly earlier)</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>5 (probably earlier)</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("document.head")}}</li> +</ul> diff --git a/files/zh-tw/web/api/document/createdocumentfragment/index.html b/files/zh-tw/web/api/document/createdocumentfragment/index.html new file mode 100644 index 0000000000..efdd4c31e6 --- /dev/null +++ b/files/zh-tw/web/api/document/createdocumentfragment/index.html @@ -0,0 +1,136 @@ +--- +title: Document.createDocumentFragment() +slug: Web/API/Document/createDocumentFragment +tags: + - API + - DOM + - 參考 + - 文本片段 + - 方法 +translation_of: Web/API/Document/createDocumentFragment +--- +<div>{{ApiRef("DOM")}}</div> + +<p>建立新的 {{domxref("DocumentFragment")}}.</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">var <var>fragment</var> = document.createDocumentFragment(); +</pre> + +<p><code>fragment </code>是 {{domxref("DocumentFragment")}} 的一個參考物件。</p> + +<h2 id="描述">描述</h2> + +<p><code>DocumentFragment</code>s 是 DOM 節點(Nodes)。他們不會成為 DOM主幹的一部份。最常見的作法是先建立文本片段 (document fragment)，然後將元素 (element) 加入文本片段中，最後再將文本片段加入 DOM 樹中。在 DOM 樹中，文本片段將會被他所有的子元素取代。</p> + +<p>正因為文本片段是存在<strong>記憶體</strong>中，並且不是 DOM 主幹的一部分，增加子元素並不會導致網頁重刷 (<a href="https://developers.google.com/speed/articles/reflow?csw=1">reflow</a>)(重新計算元素的位置和幾何)。因此採用文本片段通常會有比較好的效能表現 (<a href="http://ejohn.org/blog/dom-documentfragments/">better performance</a>)。</p> + +<h2 id="舉例">舉例</h2> + +<p>這個例子中用清單來呈現主流瀏覽器。</p> + +<h3 id="HTML">HTML</h3> + +<pre class="brush: html"><ul id="ul"> +</ul></pre> + +<h3 id="JavaScript">JavaScript</h3> + +<pre class="brush: js">var element = document.getElementById('ul'); // assuming ul exists +var fragment = document.createDocumentFragment(); +var browsers = ['Firefox', 'Chrome', 'Opera', + 'Safari', 'Internet Explorer']; + +browsers.forEach(function(browser) { + var li = document.createElement('li'); + li.textContent = browser; + fragment.appendChild(li); +}); + +element.appendChild(fragment); +</pre> + +<h3 id="結果">結果</h3> + +<p>在 <a href="https://jsfiddle.net/a0nn690f/">jsfiddle </a>上看範例結果。</p> + +<h2 id="規格">規格</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">規格</th> + <th scope="col">狀態</th> + <th scope="col">註解</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{SpecName('DOM WHATWG', '#dom-document-createdocumentfragment', 'Document.createDocumentFragment()')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>Initial definition in the DOM 1 specification.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<div>{{CompatibilityTable}}</div> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>特色</th> + <th>Firefox (Gecko)</th> + <th>Chrome</th> + <th>Edge</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>基礎支援</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>特色</th> + <th>Firefox Mobile (Gecko)</th> + <th>Android</th> + <th>Edge</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>基礎支援</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="更多參考">更多參考</h2> + +<ul> + <li>{{domxref("DOMImplementation.createDocument", "document.implementation.createDocument()")}}</li> + <li>{{domxref("documentFragment")}}</li> +</ul> diff --git a/files/zh-tw/web/api/document/createelement/index.html b/files/zh-tw/web/api/document/createelement/index.html new file mode 100644 index 0000000000..2d847004cc --- /dev/null +++ b/files/zh-tw/web/api/document/createelement/index.html @@ -0,0 +1,179 @@ +--- +title: Document.createElement() +slug: Web/API/Document/createElement +translation_of: Web/API/Document/createElement +--- +<div>{{APIRef("DOM")}}</div> + +<p>於 <a href="/en-US/docs/Web/HTML">HTML</a> 文件中，<strong><code>Document.createElement()</code></strong> 方法可以依指定的標籤名稱（<code>tagName</code>）建立 HTML 元素，或是在未定義標籤名稱下建立一個 {{domxref("HTMLUnknownElement")}}。在 <a href="/en-US/docs/Mozilla/Tech/XUL">XUL</a> 文件中，<code>Document.createElement()</code> 將會建立指定的 XUL 元素。而在其它文件，則會建立一個 namespace URI 為 <code>null</code> 的元素。</p> + +<p>若要明確指定元素的 namespace URI，請使用 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Document/createElementNS" title="Creates an element with the specified namespace URI and qualified name."><code>document.createElementNS()</code></a>。</p> + +<h2 id="語法">語法</h2> + +<pre class="brush: js"><var>var <em>element</em></var> = <var>document</var>.createElement(<em><var>tagName[, options]</var></em>); +</pre> + +<h3 id="參數">參數</h3> + +<dl> + <dt><code>tagName</code></dt> + <dd>一個指定類型給所創建的元素的字串。{{domxref("Node.nodeName", "nodeName")}} 創建的元素由 <code>tagName</code> 的值初始，不要使用吻合名稱（例如 "html:a"）。當該方法在 HTML 文件中被調用時，<code>createElement()</code> 會先將 <code>tagName</code> 轉化為小寫後再創建元素。在 Firefox、Opera 和 Chrome，<code>createElement(null)</code> 與 <code>createElement("null")</code> 作用相同。</dd> + <dt><code>options</code>{{optional_inline}}</dt> + <dd>選擇性 <code>ElementCreationOptions</code> 物件包含一個屬性 <code>is</code>，它的值是先前使用<code>customElements.define()</code> 所定義的自定義元素的標籤名稱。為了與以前的 <a href="https://www.w3.org/TR/custom-elements/">自定義元素規範</a> 相容，一些瀏覽器將允許你在此傳遞一個字串而非物件，其字串的值就是自定義元件的標籤名稱。了解更多訊息以及如何使用此參數，可以參閱 <a href="https://developers.google.com/web/fundamentals/primers/customelements/#extendhtml">擴展原生 HTML 元素</a> 。</dd> + <dd>新元素將被賦予一個 <code>is</code> 屬性，其值就是自定義元素的標籤名稱。自定義元素算是實驗中的功能，因此目前只作用於部分瀏覽器中。</dd> +</dl> + +<h3 id="回傳值">回傳值</h3> + +<p>一個新的 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Element" title="The Element interface represents an object of a Document. This interface describes methods and properties common to all kinds of elements. Specific behaviors are described in interfaces which inherit from Element but add additional functionality."><code>Element</code></a>.</p> + +<h2 id="範例">範例</h2> + +<p>這邊創建一個新的 <code><div></code> ，並將它插入到 ID <code>div1</code> 之前。</p> + +<h3 id="HTML">HTML</h3> + +<pre class="brush:html"><!DOCTYPE html> +<html> +<head> + <title>||Working with elements||</title> +</head> +<body> + <div id="div1">The text above has been created dynamically.</div> +</body> +</html> +</pre> + +<h3 id="JavaScript"><span style="line-height: normal;">JavaScript</span></h3> + +<pre class="brush:js">document.body.onload = addElement; + +function addElement () { + // create a new div element + // and give it some content + var newDiv = document.createElement("div"); + var newContent = document.createTextNode("Hi there and greetings!"); + newDiv.appendChild(newContent); //add the text node to the newly created div. + + // add the newly created element and its content into the DOM + var currentDiv = document.getElementById("div1"); + document.body.insertBefore(newDiv, currentDiv); +}</pre> + +<p>{{EmbedLiveSample("Example", 500, 50)}}</p> + +<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('DOM WHATWG', "#dom-document-createelement", "Document.createElement")}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td></td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}<sup>[1][2]</sup></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>options</code> argument</td> + <td>{{CompatVersionUnknown}}<sup>[3]</sup></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoDesktop(50)}}<sup>[4][5]</sup></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</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>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + <th>Chrome for Android</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>options</code> argument</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}<sup>[3]</sup></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}<sup>[3]</sup></td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Starting with Gecko 22.0 {{geckoRelease("22.0")}} <code>createElement()</code> no longer uses the {{domxref("HTMLSpanElement")}} interface when the argument is "bgsounds", "multicol", or "image". Instead, <code>HTMLUnknownElement</code> is used for "bgsound" and "multicol" and {{domxref("HTMLElement")}} <code>HTMLElement</code> is used for "image".</p> + +<p>[2] The Gecko implementation of <code>createElement</code> doesn't conform to the DOM spec for XUL and XHTML documents: <code>localName</code> and <code>namespaceURI</code> are not set to <code>null</code> on the created element. See {{ Bug(280692) }} for details.</p> + +<p>[3] In previous versions of the specification, this argument was just a string whose value was the custom element's tag name. For example: <code>document.createElement("button", "custom-button")</code> rather than <code>document.createElement("button", {id: "custom-button"})</code>. For the sake of backwards compatibility, Chrome accepts both forms.</p> + +<p>[4] See [3] above: like Chrome, Firefox accepts a string instead of an object here, but only from version 51 onwards. In version 50, <code>options</code> must be an object.</p> + +<p>[5] To experiment with custom elements in Firefox, you must set the <code>dom.webcomponents.enabled</code> and <code>dom.webcomponents.customelements.enabled</code> preferences to <code>true</code>.</p> + +<h2 id="See_also" name="See_also">參見</h2> + +<ul> + <li>{{domxref("Node.removeChild()")}}</li> + <li>{{domxref("Node.replaceChild()")}}</li> + <li>{{domxref("Node.appendChild()")}}</li> + <li>{{domxref("Node.insertBefore()")}}</li> + <li>{{domxref("Node.hasChildNodes()")}}</li> +</ul> diff --git a/files/zh-tw/web/api/document/createrange/index.html b/files/zh-tw/web/api/document/createrange/index.html new file mode 100644 index 0000000000..93703c54bb --- /dev/null +++ b/files/zh-tw/web/api/document/createrange/index.html @@ -0,0 +1,33 @@ +--- +title: Document.createRange() +slug: Web/API/Document/createRange +translation_of: Web/API/Document/createRange +--- +<div>{{APIRef("DOM")}}</div> + +<p>回傳一 {{domxref("Range")}} 物件。</p> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox">range = document.createRange(); +</pre> + +<p><code>創造 range</code> 為 {{domxref("Range")}} 物件.</p> + +<h2 id="Example" name="Example">示例</h2> + +<pre class="brush:js">var range = document.createRange(); + +range.setStart(startNode, startOffset); +range.setEnd(endNode, endOffset); +</pre> + +<h2 id="Notes" name="Notes">註意</h2> + +<p>當 <code>Range</code> 被創建之後，必須先設定其範圍初始點及結束點， 才能使用大部分 {{domxref("Range")}} 所提供的方法。</p> + +<h2 id="Specification" name="Specification">規範</h2> + +<ul> + <li><a class="external" href="http://www.w3.org/TR/DOM-Level-2-Traversal-Range/ranges.html#Level2-DocumentRange-method-createRange">DOM Level 2 Range: DocumentRange.createRange</a></li> +</ul> diff --git a/files/zh-tw/web/api/document/createtextnode/index.html b/files/zh-tw/web/api/document/createtextnode/index.html new file mode 100644 index 0000000000..80d3d562b9 --- /dev/null +++ b/files/zh-tw/web/api/document/createtextnode/index.html @@ -0,0 +1,120 @@ +--- +title: Document.createTextNode() +slug: Web/API/Document/createTextNode +translation_of: Web/API/Document/createTextNode +--- +<div>{{APIRef("DOM")}}</div> + +<p>創建一個新的文字節點.</p> + +<h2 id="Syntax">Syntax</h2> + +<pre class="syntaxbox"><var>var text</var> = document.createTextNode(<var>data</var>); +</pre> + +<ul> + <li><font face="Consolas, Liberation Mono, Courier, monospace">文字屬於一個文字節點</font>.</li> + <li><font face="Consolas, Liberation Mono, Courier, monospace">將含有數據的串加入文字節點中</font>.</li> +</ul> + +<h2 id="Example">Example</h2> + +<pre class="brush:js"><!DOCTYPE html> +<html lang="en"> +<head> +<title>createTextNode example</title> +<script> +function addTextNode(text) { + var newtext = document.createTextNode(text), + p1 = document.getElementById("p1"); + + p1.appendChild(newtext); +} +</script> +</head> + +<body> + <button onclick="addTextNode('YES! ');">YES!</button> + <button onclick="addTextNode('NO! ');">NO!</button> + <button onclick="addTextNode('WE CAN! ');">WE CAN!</button> + + <hr /> + + <p id="p1">First line of paragraph.</p> +</body> +</html> +</pre> + +<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("DOM3 Core", "core.html#ID-1975348127", "Document.createTextNode()")}}</td> + <td>{{Spec2("DOM3 Core")}}</td> + <td>No change</td> + </tr> + <tr> + <td>{{SpecName("DOM2 Core", "core.html#ID-1975348127", "Document.createTextNode()")}}</td> + <td>{{Spec2("DOM2 Core")}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{CompatibilityTable}}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> diff --git a/files/zh-tw/web/api/document/defaultview/index.html b/files/zh-tw/web/api/document/defaultview/index.html new file mode 100644 index 0000000000..58905ebdeb --- /dev/null +++ b/files/zh-tw/web/api/document/defaultview/index.html @@ -0,0 +1,94 @@ +--- +title: Document.defaultView +slug: Web/API/Document/defaultView +translation_of: Web/API/Document/defaultView +--- +<div>{{ApiRef}}</div> + +<p>在瀏覽器中，<strong><code>document.defaultView</code></strong> 屬性會指向一個目前 {{Glossary("Browsing_context", "document")}} 所屬的 {{domxref("Window", "window")}} 物件，若無則為 <code>null</code>。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">var <var>win</var> = document.defaultView;</pre> + +<p>此為唯讀屬性。</p> + +<h2 id="規範">規範</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-document-defaultview', 'Document.defaultView')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>No change</td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', 'browsers.html#dom-document-defaultview', 'Document.defaultView')}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<div>{{CompatibilityTable}}</div> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Firefox (Gecko)</th> + <th>Chrome</th> + <th>Edge</th> + <th>Internet Explorer</th> + <th>Edge</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatIE("9.0")}}</td> + <td>0.10</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Firefox Mobile (Gecko)</th> + <th>Android</th> + <th>Edge</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> diff --git a/files/zh-tw/web/api/document/designmode/index.html b/files/zh-tw/web/api/document/designmode/index.html new file mode 100644 index 0000000000..9f04db7952 --- /dev/null +++ b/files/zh-tw/web/api/document/designmode/index.html @@ -0,0 +1,114 @@ +--- +title: Document.designMode +slug: Web/API/Document/designMode +tags: + - API + - Document + - HTML DOM + - NeedsBrowserCompatibility + - Property +translation_of: Web/API/Document/designMode +--- +<div>{{ ApiRef() }}</div> + +<div> </div> + +<h2 id="Summary" name="Summary">概要</h2> + +<p><code>document.designMode</code> 控制整個文件是否能夠編輯。可用的數值是 <code>"on"</code> 和 <code>"off"</code>。根據規範，這個屬性預設值為 <code>"off"</code>。Firefox 遵從這個標準。較早以前的 Chrome 和 IE 預設值是 <code>"inherit"</code>。從 Chrome 43 起，預設值是 「<code>off</code>」；不再支援「<code>inherit</code>」。在 IE6-10 中，數值為大寫英文字母。</p> + +<h2 id="語法">語法</h2> + +<pre class="brush: js">var mode = document.designMode; +document.designMode = "on"; +document.designMode = "off";</pre> + +<h2 id="Example" name="Example">範例</h2> + +<p>讓 {{HTMLElement("iframe")}} 的文件可以給使用者編輯：</p> + +<pre>iframeNode.contentDocument.designMode = "on"; +</pre> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">註解</th> + </tr> + <tr> + <td>{{SpecName('HTML WHATWG', '#making-entire-documents-editable:-the-designmode-idl-attribute', 'designMode')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性" style="font-size: 2.14285714285714rem;">瀏覽器相容性</h2> + +<p>{{ CompatibilityTable() }}</p> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th style="line-height: 16px;">功能</th> + <th style="line-height: 16px;">Chrome</th> + <th style="line-height: 16px;">Edge</th> + <th style="line-height: 16px;">Firefox (Gecko)</th> + <th style="line-height: 16px;">Internet Explorer</th> + <th style="line-height: 16px;">Opera</th> + <th style="line-height: 16px;">Safari</th> + </tr> + <tr> + <td>基本支援</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatVersionUnknown() }}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th style="line-height: 16px;">功能</th> + <th style="line-height: 16px;">Android</th> + <th style="line-height: 16px;">Android Webview</th> + <th style="line-height: 16px;">Edge</th> + <th style="line-height: 16px;">Firefox Mobile (Gecko)</th> + <th style="line-height: 16px;">IE Mobile</th> + <th style="line-height: 16px;">Opera Mobile</th> + <th style="line-height: 16px;">Safari Mobile</th> + <th style="line-height: 16px;">Chrome for Android</th> + </tr> + <tr> + <td>基本支援</td> + <td>{{CompatNo}}</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatVersionUnknown() }}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="See_also" name="See_also">參考</h2> + +<ul> + <li><a href="/zh-TW/docs/Rich-Text_Editing_in_Mozilla">Rich-Text Editing in Mozilla</a></li> + <li>{{domxref("HTMLElement.contentEditable")}}</li> + <li><a href="https://msdn.microsoft.com/en-us/library/ms533720(v=vs.85).aspx">designMode property</a> on MSDN</li> +</ul> diff --git a/files/zh-tw/web/api/document/documentelement/index.html b/files/zh-tw/web/api/document/documentelement/index.html new file mode 100644 index 0000000000..aa3f5db82d --- /dev/null +++ b/files/zh-tw/web/api/document/documentelement/index.html @@ -0,0 +1,60 @@ +--- +title: Document.documentElement +slug: Web/API/Document/documentElement +translation_of: Web/API/Document/documentElement +--- +<p>{{ ApiRef("DOM") }}</p> + +<p><code><strong>Document.documentElement</strong></code> 會回傳目前文件（{{domxref("document")}}）中的根元素（{{domxref("Element")}}），如：HTML 文件中的 <code><html></code> 元素。</p> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox">var <em>element</em> = document.documentElement; +</pre> + +<h2 id="Example" name="Example">範例</h2> + +<pre class="brush:js">var rootElement = document.documentElement; +var firstTier = rootElement.childNodes; + +// firstTier is the NodeList of the direct children of the root element +for (var i = 0; i < firstTier.length; i++) { + // do something with each direct kid of the root element + // as firstTier[i] +}</pre> + +<h2 id="Notes" name="Notes">備註</h2> + +<p>對於所有非空的 HTML 文件， <code>document.documentElement</code> 將會是一個 {{HTMLElement("html")}} 元素 ; 對於所有非空的 XML 文件，<code>document.documentElement</code> 則會是文件的根元素。</p> + +<h2 id="Specification" name="Specification">規範</h2> + +<table class="spectable standard-table"> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col"> 備註</th> + </tr> + <tr> + <td>{{SpecName('DOM2 Core','core.html#ID-87CD092','Document.documentElement')}}</td> + <td>{{Spec2('DOM2 Core')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM3 Core','core.html#ID-87CD092','Document.documentElement')}}</td> + <td>{{Spec2('DOM3 Core')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM4','#dom-document-documentelement','Document.documentElement')}}</td> + <td>{{Spec2('DOM4')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM WHATWG','#dom-document-documentelement','Document.documentElement')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td> </td> + </tr> + </tbody> +</table> diff --git a/files/zh-tw/web/api/document/execcommand/index.html b/files/zh-tw/web/api/document/execcommand/index.html new file mode 100644 index 0000000000..c06cd0d89c --- /dev/null +++ b/files/zh-tw/web/api/document/execcommand/index.html @@ -0,0 +1,172 @@ +--- +title: Document.execCommand() +slug: Web/API/Document/execCommand +translation_of: Web/API/Document/execCommand +--- +<div>{{ApiRef("DOM")}}{{Obsolete_header}}</div> + +<p><span class="seoSummary">當 HTML 文件（document）被切換到 <code><a href="/en-US/docs/Web/API/Document/designMode">designMode</a></code> 時，它的 <code>document</code> 物件就會對外暴露 <strong><code>execCommand</code></strong> 方法作為操控目前可編輯區域的指令，譬如 <a href="/en-US/docs/Web/HTML/Element/input">form inputs</a> 或 <code><a href="/en-US/docs/Web/HTML/Global_attributes/contenteditable">contentEditable</a></code> 元素。</span></p> + +<p>多數的指令會作用在文件的<a href="/en-US/docs/Web/API/Selection">選取</a> （粗體、斜體等），而其他則像是插入新的元素（新增一個連結）或是影響一整列的文字（縮排）。當使用 <code>contentEditable</code> 時， <code>execCommand()</code> 會作用在目前活躍的可編輯元素上。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><em>document</em>.execCommand(<em>aCommandName</em>, <em>aShowDefaultUI</em>, <em>aValueArgument</em>) +</pre> + +<h3 id="回傳值">回傳值</h3> + +<p>如果該指令不被支援或停用將回傳一個 <code>false</code> 的 {{jsxref('Boolean')}} 值。</p> + +<div class="note"> +<p><strong>備註</strong>：只有在使用者互動的部分回傳 <code>true</code> 。請不要嘗試在呼叫指令前使用回傳值來確認瀏覽器是否支援。</p> +</div> + +<h3 id="參數">參數</h3> + +<dl> + <dt><code>aCommandName</code></dt> + <dd>一個 {{domxref("DOMString")}} 作為指定要執行的指令。所有可用的指令列表請見 {{anch("Commands")}} 。</dd> + <dt><code>aShowDefaultUI</code></dt> + <dd>一個 {{jsxref("Boolean")}} 作為指示是否顯示預設的使用者介面。 Mozilla 並未實作這項功能。</dd> + <dt><code>aValueArgument</code></dt> + <dd>針對需要提供輸入引數的指令，藉由 {{domxref("DOMString")}} 提供相關的資訊。譬如， <code>insertImage</code> 需要提供圖片的 URL 。若沒有引數的需求則可指定為 <code>null</code> 。</dd> +</dl> + +<h3 id="指令">指令</h3> + +<dl> + <dt><code>backColor</code></dt> + <dd>變更文件的背景色彩。在 <code>styleWithCss</code> 模式中，它作用於涵蓋區域的背景色彩。這個指令需要提供一個 {{cssxref("<color>")}} 值字串作為引數值。請留意， Internet Explorer 使用這個指令作為設定文字的背景色彩。</dd> + <dt><code>bold</code></dt> + <dd>切換選取區域插入點的粗體與否。 Internet Explorer 使用 {{HTMLElement("strong")}} 標籤而不是 {{HTMLElement("b")}}.</dd> + <dt><code>ClearAuthenticationCache</code></dt> + <dd>清除所有快取中的驗證憑證。</dd> + <dt><code>contentReadOnly</code></dt> + <dd>使內容文件成為唯讀或可編輯。此指令需要提供布林值 true/false 作為引數值。（Internet Explorer 不支援）。</dd> + <dt><code>copy</code></dt> + <dd>複製目前選取的區域到剪貼簿。各個瀏覽器對於這個指令的行為可能有所差異且不斷變更。如果你有使用這個指令的情境，請先查閱相容性表格來決定如何使用。</dd> + <dt><code>createLink</code></dt> + <dd>對選取的區域建立超連結，僅限於有選取內容。需要提供一個 <a href="/en-US/docs/Archive/Mozilla/URIs_and_URLs">URI</a> 字串值作為超連結的 <code>href</code> 。 URI 必須最少包含一個字元且可以是空白字元（Internet Explorer 會建立一個 <code>null</code> 值的連結）。</dd> + <dt><code>cut</code></dt> + <dd>移除目前選取的區域並複製到剪貼簿。各個瀏覽器對於這個指令的行為可能有所差異且不斷變更。使用細節請查閱<a href="#Browser_compatibility">相容性表格</a>。</dd> + <dt><code>decreaseFontSize</code></dt> + <dd>在選取區域或插入點的前後加入一個 {{HTMLElement("small")}} 標籤（ Internet Explorer 不支援）</dd> + <dt><code>defaultParagraphSeparator</code></dt> + <dd>變更可編輯文字區域於新增段落時的段落分隔器。更多細節請查閱 <a href="/zh-TW/docs/Web/Guide/HTML/Editable_content#Differences_in_markup_generation">產生 markup 的區別</a>。</dd> + <dt><code>delete</code></dt> + <dd>刪除目前選取的區域。</dd> + <dt><code>enableAbsolutePositionEditor</code></dt> + <dd>啟用或停用用於移動絕對定位元素的抓取器。這個指令在 Firefox 63 Beta/Dev 版本中預設停用（{{bug(1449564)}}）。</dd> + <dt><code>enableInlineTableEditing</code></dt> + <dd>啟用或停用表格的列 / 欄的插入及刪除。此指令在 Firefox 63 Beta/Dev 版本中預設停用 ({{bug(1449564)}})。</dd> + <dt><code>enableObjectResizing</code></dt> + <dd>啟用或停用圖片、表格、絕對定位元素、其他可重設大小物件的重設大小處理。此指令在 Firefox 63 Beta/Dev 版本中預設停用 ({{bug(1449564)}})。</dd> + <dt><code>fontName</code></dt> + <dd>變更選取區域或插入點的字型名稱。此指令需要字型名稱字串（如「Arial」）作為引數值。</dd> + <dt><code>fontSize</code></dt> + <dd>變更選取區域或插入點的字型大小。此指令需要 <code>1</code>-<code>7</code> 的整數作為引數值。</dd> + <dt><code>foreColor</code></dt> + <dd>變更選取區域或插入點的字型色彩。此指令需要十六進位的色彩字串作為引數值。</dd> + <dt><code>formatBlock</code></dt> + <dd>在目前選取區域的前後加入一個 HTML 區塊層級元素，若選取區域已經存在區塊元素則取代之。（在 Firefox 中， {{HTMLElement("blockquote")}} 是個例外——它會包裹住任何所包含的區塊元素）。 此指令需要一個標籤名稱字串作為引數值。幾乎所有區塊層級元素都可以使用（Internet Explorer and Edge 僅支援標題標籤 <code>H1</code>–<code>H6</code> 、 <code>ADDRESS</code> 、 <code>PRE</code> 且必須由角括號包裹起來，譬如 <code>"<H1>"</code> ）。</dd> + <dt><code>forwardDelete</code></dt> + <dd>刪除游標位置後的字元，等同於在 Windows 按下 Delete 鍵盤按鍵。</dd> + <dt><code>heading</code></dt> + <dd>在選取區域或插入點前後加入一個標題元素。此指令需要標籤名稱字串作為引數值（例：<code>"H1"</code>, <code>"H6"</code> ）（Internet Explorer 及 Safari 不支援）。</dd> + <dt><code>hiliteColor</code></dt> + <dd>變更選取區域或插入點的背景色彩。此指令需要一個色彩字串作為引數值。 <code>useCSS</code> 必須為 <code>true</code> 才能有作用（Internet Explorer 不支援）。</dd> + <dt><code>increaseFontSize</code></dt> + <dd>在選取區域或插入點前後加入一個 {{HTMLElement("big")}} 標題（Internet Explorer 不支援）。</dd> + <dt><code>indent</code></dt> + <dd>縮排選取區域或插入點所包含的列。在 Firefox ，如果選取的範圍跨越多列且不同的縮排層級，只有選取中最淺層縮排列的才會被縮排。</dd> + <dt><code>insertBrOnReturn</code></dt> + <dd>控制 Enter 按鍵按下時在目前區塊元素中插入 {{HTMLElement("br")}} 元素或分割成為兩個元素（Internet Explorer 不支援）。</dd> + <dt><code>insertHorizontalRule</code></dt> + <dd>在插入點插入一個 {{HTMLElement("hr")}} 元素或以它取代選取的內容。</dd> + <dt><code>insertHTML</code></dt> + <dd>在插入點插入一個 HTML 字串（會刪除選取內容）需要一個有效的 HTML 字串作為引數值（Internet Explorer 不支援）。</dd> + <dt><code>insertImage</code></dt> + <dd>在插入點插入一個圖片（會刪除選取內容）。需要一個 URL 字串作為圖片的 <code>src</code> 引數值。這個需求跟 <code>createLink</code> 的字串是一樣的。</dd> + <dt><code>insertOrderedList</code></dt> + <dd>在選取區域或插入點建立一個<a href="/zh-TW/docs/Web/HTML/Element/ol">有序的清單</a>。</dd> + <dt><code>insertUnorderedList</code></dt> + <dd>在選取區域或插入點建立一個<a href="/zh-TW/docs/Web/HTML/Element/ul">無序的清單</a>。</dd> + <dt><code>insertParagraph</code></dt> + <dd>在選取區域或目前列的前後插入<a href="/zh-TW/docs/Web/HTML/Element/p">段落</a>（Internet Explorer 會在插入點插入段落並刪除選取的內容）。</dd> + <dt><code>insertText</code></dt> + <dd>在插入點處插入給予的純文字（選取內容將被刪除）。</dd> + <dt><code>italic</code></dt> + <dd>切換選取區域或插入點的斜體開關（Internet Explorer 使用 {{HTMLElement("em")}} 元素而不是 {{HTMLElement("i")}} ）。</dd> + <dt><code>justifyCenter</code></dt> + <dd>置中對齊選取區域或插入點的內容。</dd> + <dt><code>justifyFull</code></dt> + <dd>左右對齊選取區域或插入點的內容。</dd> + <dt><code>justifyLeft</code></dt> + <dd>靠左對齊選取區域或插入點的內容。</dd> + <dt><code>justifyRight</code></dt> + <dd>靠右對齊選取區域或插入點的內容。</dd> + <dt><code>outdent</code></dt> + <dd>凸排選取區域或插入點所包含的列。</dd> + <dt><code>paste</code></dt> + <dd>在目前的插入點貼上剪貼簿的內容（取代目前選取的項目）。網頁內容無法使用。詳閱 [1]。</dd> + <dt><code>redo</code></dt> + <dd>復原上一個取消的指令。</dd> + <dt><code>removeFormat</code></dt> + <dd>移除目前選取區域所有的格式。</dd> + <dt><code>selectAll</code></dt> + <dd>選取可編輯區域的所有內容。</dd> + <dt><code>strikeThrough</code></dt> + <dd>切換選取區域或插入點的刪除線開關。</dd> + <dt><code>subscript</code></dt> + <dd>切換選取區域或插入點的 <a href="/zh-TW/docs/Web/HTML/Element/sub">subscript</a> 開關。</dd> + <dt><code>superscript</code></dt> + <dd>切換選取區域或插入點的 <a href="/zh-TW/docs/Web/HTML/Element/sup">superscript</a> 開關。</dd> + <dt><code>underline</code></dt> + <dd>切換選取區域或插入點的<a href="/zh-TW/docs/Web/HTML/Element/u">底線</a>開關。</dd> + <dt><code>undo</code></dt> + <dd>取消上一個執行的指令。</dd> + <dt><code>unlink</code></dt> + <dd>從選取的超連結刪除<a href="/zh-TW/docs/Web/HTML/Element/a">錨點元素</a>。</dd> + <dt><code>useCSS</code> {{Deprecated_inline}}</dt> + <dd>針對產生的 markup 使用 HTML 標籤或 CSS。此指令需要一個布林值 true/false 作為引數值。</dd> + <dd>注意：這個引述在邏輯上是反向的（舉例：使用 <code>false</code> 會使用 CSS ，反之使用 <code>true</code> 則使用 HTML 且 Internet Explorer 不支援。這個指令已經被棄用並由 <code>styleWithCSS</code> 取而代之。</dd> + <dt><code>styleWithCSS</code></dt> + <dd>取代 <code>useCSS</code> 的指令。 <code>true</code> 會在 markup 修改 / 產生 <code>style</code> 屬性， false 會產生展示用的元素。</dd> +</dl> + +<h2 id="範例">範例</h2> + +<p>一個在 CodePen 上展示<a href="https://codepen.io/chrisdavidmills/full/gzYjag/">如果使用</a>的範例。</p> + +<h2 id="規格">規格</h2> + +<table class="spectable standard-table"> + <tbody> + <tr> + <th scope="col">規格</th> + <th scope="col">狀態</th> + <th scope="col">備註</th> + </tr> + <tr> + <td><a href="https://w3c.github.io/editing/execCommand.html#execcommand()">execCommand</a></td> + <td></td> + <td></td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + + + +<p>{{Compat("api.Document.execCommand")}}</p> + +<h2 id="相關資訊">相關資訊</h2> + +<ul> + <li>{{domxref("HTMLElement.contentEditable")}}</li> + <li>{{domxref("document.designMode")}}</li> + <li><a href="/zh-TW/docs/Rich-Text_Editing_in_Mozilla">Rich-Text Editing in Mozilla</a></li> + <li><a href="https://github.com/guardian/scribe/blob/master/BROWSERINCONSISTENCIES.md">Scribe's "Browser Inconsistencies" documentation</a> with bugs related to <code>document.execCommand</code>.</li> +</ul> diff --git a/files/zh-tw/web/api/document/forms/index.html b/files/zh-tw/web/api/document/forms/index.html new file mode 100644 index 0000000000..769d80871c --- /dev/null +++ b/files/zh-tw/web/api/document/forms/index.html @@ -0,0 +1,75 @@ +--- +title: Document.forms +slug: Web/API/Document/forms +translation_of: Web/API/Document/forms +--- +<div>{{APIRef("DOM")}}</div> + +<p><code>forms</code> 屬性會回傳一個包含目前頁面中所有 {{HTMLElement("form")}} 元素的集合物件（型別為 {{domxref("HTMLCollection")}}）。</p> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox"><var>collection</var> = document.forms;</pre> + +<h2 id="Example" name="Example">範例：取得表單資訊</h2> + +<pre class="brush:html"><!DOCTYPE html> +<html lang="en"> + +<head> +<title>document.forms example</title> +</head> + +<body> + +<form id="robby"> + <input type="button" onclick="alert(document.forms[0].id);" value="robby's form" /> +</form> + +<form id="dave"> + <input type="button" onclick="alert(document.forms[1].id);" value="dave's form" /> +</form> + +<form id="paul"> + <input type="button" onclick="alert(document.forms[2].id);" value="paul's form" /> +</form> + +</body> +</html> +</pre> + +<h2 id="範例_2：取得表單內的元素">範例 2：取得表單內的元素</h2> + +<pre class="brush: js">var selectForm = document.forms[index]; +var selectFormElement = document.forms[index].elements[index]; +</pre> + +<h2 id="Specifications" name="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-document-forms', 'Document.forms')}}</td> + <td>{{ Spec2('HTML WHATWG') }}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM2 HTML', 'html.html#ID-1689064', 'Document.forms')}}</td> + <td>{{ Spec2('DOM2 Events') }}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="See_Also" name="See_Also">參見</h2> + +<ul> + <li>{{domxref("HTMLFormElement")}}</li> +</ul> diff --git a/files/zh-tw/web/api/document/getelementsbyclassname/index.html b/files/zh-tw/web/api/document/getelementsbyclassname/index.html new file mode 100644 index 0000000000..b66647c82d --- /dev/null +++ b/files/zh-tw/web/api/document/getelementsbyclassname/index.html @@ -0,0 +1,127 @@ +--- +title: Document.getElementsByClassName() +slug: Web/API/Document/getElementsByClassName +tags: + - 待翻譯 +translation_of: Web/API/Document/getElementsByClassName +--- +<p id="Summary">{{APIRef("DOM")}}</p> + +<p>針對所有給定的 class 子元素，回傳類似陣列的物件。當呼叫 document 物件時，它會搜尋整個文件，包括根節點在內。你也可以在所有元素呼叫 {{domxref("Element.getElementsByClassName", "getElementsByClassName()")}}，那它就只會回傳含有給定 class 的特定根元素的後代元素。</p> + +<h2 id="Syntax" name="Syntax">表達式</h2> + +<pre class="syntaxbox"><var>var elements</var> = document.getElementsByClassName(<em>names</em>); // or: +<var>var elements</var> = rootElement.getElementsByClassName(<em>names</em>);</pre> + +<ul> + <li><var>elements</var> 為符合 class 名稱的 {{ domxref("HTMLCollection") }}。</li> + <li><var>names</var> 為符合 class 名稱的字串；class 名稱可以用空白分隔。</li> + <li>getElementsByClassName 可以被任何不只在 document 的元素呼叫。呼叫這個方法的元素將會成為搜尋 class 的根元素。</li> +</ul> + +<h2 id="Examples" name="Examples">範例</h2> + +<p>取得所有 class 為 “test” 的元素：</p> + +<pre class="brush: js">document.getElementsByClassName('test');</pre> + +<p>取得所有 class 為 “test” 和 “red” 的元素：</p> + +<pre class="brush: js">document.getElementsByClassName('red test');</pre> + +<p>取得所有在 id 為 '“main” 的元素裡 class 為 “test” 的元素：</p> + +<pre class="brush: js">document.getElementById('main').getElementsByClassName('test');</pre> + +<p>我們也可以藉由傳遞 {{ domxref("HTMLCollection") }} 為 <var>this </var>來使用 <code>Array.prototype</code> 的方法。下面的例子將會找到所有 class 為 “test” 的 div 元素：</p> + +<pre class="brush: js">var testElements = document.getElementsByClassName('test'); +var testDivs = Array.prototype.filter.call(testElements, function(testElement){ + return testElement.nodeName === 'DIV'; +});</pre> + +<h2 id="取得_class_是_test_的元素">取得 class 是 test 的元素</h2> + +<p>這是最常用的操作方法：</p> + +<pre><!doctype html> +<html> +<head> + <meta charset="UTF-8"> + <title>Document</title> +</head> +<body> + <div id="parent-id"> + <p>hello word1</p> + <p class="test">hello word2</p> + <p>hello word3</p> + <p>hello word4</p> + </div> + <script> + var parentDOM = document.getElementById("parent-id"); + + var test=parentDOM.getElementsByClassName("test");//test is not target element + console.log(test);//HTMLCollection[1] + + var testTarget=parentDOM.getElementsByClassName("test")[0];//year , this element is target + console.log(testTarget);//<p class="test">hello word2</p> + </script> +</body> +</html></pre> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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>{{ CompatVersionUnknown() }}</td> + <td>3.0</td> + <td>9.0</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatVersionUnknown() }}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="Specification" name="Specification">規範</h2> + +<ul> + <li><a href="https://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#dom-document-getelementsbyclassname" title="https://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#dom-document-getelementsbyclassname"><span class="external">W3C: getElementsByClassName</span></a></li> +</ul> diff --git a/files/zh-tw/web/api/document/head/index.html b/files/zh-tw/web/api/document/head/index.html new file mode 100644 index 0000000000..7ecde675ea --- /dev/null +++ b/files/zh-tw/web/api/document/head/index.html @@ -0,0 +1,114 @@ +--- +title: Document.head +slug: Web/API/Document/head +translation_of: Web/API/Document/head +--- +<p>{{APIRef("DOM")}}</p> + +<p>回傳當前文件的 {{HTMLElement("head")}} 元素。如果該文件有超過一個 <code><head></code> 元素，那只會回傳第一個 <code><head></code> 元素。</p> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox"><em>var objRef</em> = document.head; +</pre> + +<h2 id="Example" name="Example">範例</h2> + +<pre class="brush: js">// in HTML: <head id="my-document-head"> +var aHead = document.head; + +alert(aHead.id); // "my-document-head"; + +alert( document.head === document.querySelector("head") ); // true +</pre> + +<h2 id="備註">備註</h2> + +<p><code>document.head</code> 是「唯讀」。若是想要將 <code>document.head</code> 改成別的值會失敗，這時有些瀏覽器不會告知任何錯誤訊息；有些，例如在 <a href="/zh-TW/docs/Web/JavaScript/Reference/Functions_and_function_scope/Strict_mode">ECMAScript Strict 模式下</a> 的 Gecko 瀏覽器，會給出 <code><a href="/zh-TW/docs/Web/JavaScript/Reference/Global_Objects/TypeError">TypeError</a></code> 異常。</p> + +<h2 id="規範">規範</h2> + +<table class="spectable standard-table"> + <tbody> + <tr> + <th scope="col">Specification</th> + <th scope="col">Status</th> + <th scope="col">Comment</th> + </tr> + <tr> + <td>{{SpecName('HTML WHATWG','dom.html#dom-document-head','Document.head')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>Initial definition.</td> + </tr> + <tr> + <td>{{SpecName('HTML5.1','dom.html#dom-document-head','Document.head')}}</td> + <td>{{Spec2('HTML5.1')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C','dom.html#dom-document-head','Document.head')}}</td> + <td>{{Spec2('HTML5 W3C')}}</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>Edge</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>Basic support</td> + <td>4.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("2")}}</td> + <td>9.0</td> + <td>11.0</td> + <td>5.0</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("2")}}</td> + <td>9.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("document.body")}}</li> +</ul> diff --git a/files/zh-tw/web/api/document/index.html b/files/zh-tw/web/api/document/index.html new file mode 100644 index 0000000000..ca1c9830b7 --- /dev/null +++ b/files/zh-tw/web/api/document/index.html @@ -0,0 +1,446 @@ +--- +title: Document +slug: Web/API/Document +tags: + - API + - DOM + - Gecko + - MakeBrowserAgnostic + - NeedsTranslation + - Reference + - TopicStub +translation_of: Web/API/Document +--- +<div>{{APIRef}}</div> + +<div></div> + +<p><span class="seoSummary"><strong><code>Document</code></strong> 介面代表所有在瀏覽器中載入的網頁，也是作為網頁內容 <a href="/en-US/docs/Using_the_W3C_DOM_Level_1_Core" title="Using_the_W3C_DOM_Level_1_Core">DOM 樹</a></span>（包含如 {{HTMLElement("body")}}、{{HTMLElement("table")}} 與其它的{{domxref("Element", "元素")}}）的進入點。<code>Document</code> 提供了網頁文件所需的通用函式，例如取得頁面 URL 或是建立網頁文件中新的元素節點等。</p> + +<p>{{inheritanceDiagram}}</p> + +<p><code>Document</code> 介面描述了各種類型文件的共同屬性與方法。根據文件的類型（如 <a href="/zh-TW/docs/HTML" title="HTML">HTML</a>、<a href="/zh-TW/docs/XML" title="XML">XML</a>、SVG 等），也會擁有各自的 API：HTML 文件（content type 為 <code>text/html</code>）實作了 {{domxref("HTMLDocument")}} 介面，而 XML 及 SVG 文件實作了 {{domxref("XMLDocument")}} 介面。</p> + +<p>請注意 <code>window.document</code> 物件為 <code>HTMLDocument</code> 所建構。</p> + +<h2 id="Properties" name="Properties">屬性</h2> + +<p><em>這個介面繼承了 {{domxref("Node")}} 以及 {{domxref("EventTarget")}} 介面。</em></p> + +<dl> + <dt>{{domxref("Document.all")}} {{Deprecated_inline}} {{non-standard_inline}}</dt> + <dd>Provides access to all elements with an <code>id</code>. This is a legacy, non-standard interface and you should use the {{domxref("document.getElementById()")}} method instead.</dd> + <dt>{{domxref("Document.async")}} {{Deprecated_inline}}</dt> + <dd>Used with {{domxref("Document.load")}} to indicate an asynchronous request.</dd> + <dt>{{domxref("Document.characterSet")}} {{readonlyinline}}</dt> + <dd>Returns the character set being used by the document.</dd> + <dt>{{domxref("Document.charset")}} {{readonlyinline}} {{Deprecated_inline}}</dt> + <dd>Alias of {{domxref("Document.characterSet")}}. Use this property instead.</dd> + <dt>{{domxref("Document.compatMode")}} {{readonlyinline}} {{experimental_inline}}</dt> + <dd>Indicates whether the document is rendered in <em>quirks</em> or <em>strict</em> mode.</dd> + <dt>{{domxref("Document.contentType")}} {{readonlyinline}} {{experimental_inline}}</dt> + <dd>Returns the Content-Type from the MIME Header of the current document.</dd> + <dt>{{domxref("Document.doctype")}} {{readonlyinline}}</dt> + <dd>回傳目前文件的 Document Type Definition（DTD）。</dd> + <dt>{{domxref("Document.documentElement")}} {{readonlyinline}}</dt> + <dd>回傳當前文件 {{domxref("Document")}} 的根元素。以 HTML documents為例：它會回傳 {{HTMLElement("html")}} 這項元素。</dd> + <dt>{{domxref("Document.documentURI")}} {{readonlyinline}}</dt> + <dd>Returns the document location as a string.</dd> + <dt>{{domxref("Document.domConfig")}} {{Deprecated_inline}}</dt> + <dd>Should return a {{domxref("DOMConfiguration")}} object.</dd> + <dt>{{domxref("Document.fullscreen")}} {{obsolete_inline}}</dt> + <dd><code>true</code> when the document is in {{domxref("Using_full-screen_mode","full-screen mode")}}.</dd> + <dt>{{domxref("Document.hidden")}} {{readonlyinline}}</dt> + <dd>…</dd> + <dt>{{domxref("Document.implementation")}} {{readonlyinline}}</dt> + <dd>Returns the DOM implementation associated with the current document.</dd> + <dt>{{domxref("Document.inputEncoding")}} {{readonlyinline}} {{Deprecated_inline}}</dt> + <dd>Alias of {{domxref("Document.characterSet")}}. Use this property instead.</dd> + <dt>{{domxref("Document.lastStyleSheetSet")}} {{readonlyinline}}</dt> + <dd>Returns the name of the style sheet set that was last enabled. Has the value <code>null</code> until the style sheet is changed by setting the value of {{domxref("document.selectedStyleSheetSet","selectedStyleSheetSet")}}.</dd> + <dt>{{domxref("Document.mozSyntheticDocument")}} {{non-standard_inline}} {{gecko_minversion_inline("8.0")}}</dt> + <dd>Returns a {{jsxref("Boolean")}} that is <code>true</code> only if this document is synthetic, such as a standalone image, video, audio file, or the like.</dd> + <dt>{{domxref("Document.mozFullScreenElement")}} {{readonlyinline}} {{non-standard_inline}} {{gecko_minversion_inline("9.0")}}</dt> + <dd>The element that's currently in full screen mode for this document.</dd> + <dt>{{domxref("Document.mozFullScreenEnabled")}} {{readonlyinline}} {{non-standard_inline}} {{gecko_minversion_inline("9.0")}}</dt> + <dd><code>true</code> if calling {{domxref("Element.mozRequestFullscreen()")}} would succeed in the curent document.</dd> + <dt>{{domxref("Document.pointerLockElement")}} {{readonlyinline}} {{experimental_inline}}</dt> + <dd>Returns the element set as the target for mouse events while the pointer is locked. <code>null</code> if lock is pending, pointer is unlocked, or if the target is in another document.</dd> + <dt>{{domxref("Document.preferredStyleSheetSet")}} {{readonlyinline}}</dt> + <dd>Returns the preferred style sheet set as specified by the page author.</dd> + <dt>{{domxref("Document.scrollingElement")}} {{experimental_inline}} {{readonlyinline}}</dt> + <dd>Returns a reference to the {{domxref("Element")}} that scrolls the document.</dd> + <dt>{{domxref("Document.selectedStyleSheetSet")}}</dt> + <dd>Returns which style sheet set is currently in use.</dd> + <dt>{{domxref("Document.styleSheets")}} {{readonlyinline}}</dt> + <dd>Returns a list of the style sheet objects on the current document.</dd> + <dt>{{domxref("Document.styleSheetSets")}} {{readonlyinline}}</dt> + <dd>Returns a list of the style sheet sets available on the document.</dd> + <dt>{{domxref("Document.timeline")}} {{readonlyinline}}</dt> + <dd>…</dd> + <dt>{{domxref("Document.undoManager")}} {{readonlyinline}} {{experimental_inline}}</dt> + <dd>…</dd> + <dt>{{domxref("Document.visibilityState")}} {{readonlyinline}}</dt> + <dd> + <p>Returns a <code>string</code> denoting the visibility state of the document. Possible values are <code>visible</code>, <code>hidden</code>, <code>prerender</code>, and <code>unloaded</code>.</p> + </dd> + <dt>{{domxref("Document.xmlEncoding")}} {{Deprecated_inline}}</dt> + <dd>Returns the encoding as determined by the XML declaration.</dd> + <dt>{{domxref("Document.xmlStandalone")}} {{obsolete_inline("10.0")}}</dt> + <dd>Returns <code>true</code> if the XML declaration specifies the document to be standalone (<em>e.g.,</em> An external part of the DTD affects the document's content), else <code>false</code>.</dd> + <dt>{{domxref("Document.xmlVersion")}} {{obsolete_inline("10.0")}}</dt> + <dd>Returns the version number as specified in the XML declaration or <code>"1.0"</code> if the declaration is absent.</dd> +</dl> + +<p>The <code>Document</code> interface is extended with the {{domxref("ParentNode")}} interface:</p> + +<p>{{page("/en-US/docs/Web/API/ParentNode","Properties")}}</p> + +<h3 id="HTML_文件擴充">HTML 文件擴充</h3> + +<p><em><strong><code>window.document</code></strong> 物件的部分屬性繼承自 HTML 文件的 {{domxref("HTMLDocument")}} 介面，或是來自 <code>Document</code> 從 HTML5 之後擴充的屬性。</em></p> + +<dl> + <dt>{{domxref("Document.activeElement")}} {{readonlyinline}}</dt> + <dd>Returns the currently focused element.</dd> + <dt>{{domxref("Document.alinkColor")}} {{Deprecated_inline}}</dt> + <dd>Returns or sets the color of active links in the document body.</dd> + <dt>{{domxref("Document.anchors")}}</dt> + <dd>Returns a list of all of the anchors in the document.</dd> + <dt>{{domxref("Document.applets")}} {{Deprecated_inline}}</dt> + <dd>Returns an ordered list of the applets within a document.</dd> + <dt>{{domxref("Document.bgColor")}} {{Deprecated_inline}}</dt> + <dd>Gets/sets the background color of the current document.</dd> + <dt>{{domxref("Document.body")}}</dt> + <dd>Returns the {{HTMLElement("body")}} element of the current document.</dd> + <dt>{{domxref("Document.cookie")}}</dt> + <dd>Returns a semicolon-separated list of the cookies for that document or sets a single cookie.</dd> + <dt>{{domxref("Document.defaultView")}} {{readonlyinline}}</dt> + <dd>Returns a reference to the window object.</dd> + <dt>{{domxref("Document.designMode")}}</dt> + <dd>Gets/sets the ability to edit the whole document.</dd> + <dt>{{domxref("Document.dir")}} {{readonlyinline}}</dt> + <dd>Gets/sets directionality (rtl/ltr) of the document.</dd> + <dt>{{domxref("Document.domain")}} {{readonlyinline}}</dt> + <dd>Returns the domain of the current document.</dd> + <dt>{{domxref("Document.embeds")}} {{readonlyinline}}</dt> + <dd>Returns a list of the embedded {{HTMLElement('embed')}} elements within the current document.</dd> + <dt>{{domxref("document.fgColor")}} {{Deprecated_inline}}</dt> + <dd>Gets/sets the foreground color, or text color, of the current document.</dd> + <dt>{{domxref("Document.forms")}} {{readonlyinline}}</dt> + <dd>Returns a list of the {{HTMLElement("form")}} elements within the current document.</dd> + <dt>{{domxref("Document.head")}} {{readonlyinline}}</dt> + <dd>Returns the {{HTMLElement("head")}} element of the current document.</dd> + <dt>{{domxref("Document.height")}} {{non-standard_inline}} {{obsolete_inline}}</dt> + <dd>Gets/sets the height of the current document.</dd> + <dt>{{domxref("Document.images")}} {{readonlyinline}}</dt> + <dd>Returns a list of the images in the current document.</dd> + <dt>{{domxref("Document.lastModified")}} {{readonlyinline}}</dt> + <dd>Returns the date on which the document was last modified.</dd> + <dt>{{domxref("Document.linkColor")}} {{Deprecated_inline}}</dt> + <dd>Gets/sets the color of hyperlinks in the document.</dd> + <dt>{{domxref("Document.links")}} {{readonlyinline}}</dt> + <dd>Returns a list of all the hyperlinks in the document.</dd> + <dt>{{domxref("Document.location")}} {{readonlyinline}}</dt> + <dd>Returns the URI of the current document.</dd> + <dt>{{domxref("Document.plugins")}} {{readonlyinline}}</dt> + <dd>Returns a list of the available plugins.</dd> + <dt>{{domxref("Document.readyState")}} {{readonlyinline}} {{gecko_minversion_inline("1.9.2")}}</dt> + <dd>Returns loading status of the document.</dd> + <dt>{{domxref("Document.referrer")}} {{readonlyinline}}</dt> + <dd>Returns the URI of the page that linked to this page.</dd> + <dt>{{domxref("Document.scripts")}} {{readonlyinline}}</dt> + <dd>Returns all the {{HTMLElement("script")}} elements on the document.</dd> + <dt>{{domxref("Document.title")}}</dt> + <dd>Sets or gets title of the current document.</dd> + <dt>{{domxref("Document.URL")}} {{readonlyInline}}</dt> + <dd>Returns<span style="line-height: 19.0909080505371px;"> the document location as a string.</span></dd> + <dt>{{domxref("Document.vlinkColor")}} {{Deprecated_inline}}</dt> + <dd>Gets/sets the color of visited hyperlinks.</dd> + <dt>{{domxref("Document.width")}} {{non-standard_inline}} {{obsolete_inline}}</dt> + <dd>Returns the width of the current document.</dd> +</dl> + +<h3 id="Event_handlers" name="Event_handlers">事件處理器</h3> + +<dl> + <dt>{{domxref("Document.onafterscriptexecute")}} {{non-standard_inline}}</dt> + <dd>Represents the event handling code for the {{event("afterscriptexecute")}} event.</dd> + <dt>{{domxref("Document.onbeforescriptexecute")}} {{non-standard_inline}}</dt> + <dd>Represents the event handling code for the {{event("beforescriptexecute")}} event.</dd> + <dt>{{domxref("Document.oncopy")}} {{non-standard_inline}}</dt> + <dd>Represents the event handling code for the {{event("copy")}} event.</dd> + <dt>{{domxref("Document.oncut")}} {{non-standard_inline}}</dt> + <dd>Represents the event handling code for the {{event("cut")}} event.</dd> + <dt>{{domxref("Document.onfullscreenchange")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("fullscreenchange")}} event is raised.</dd> + <dt>{{domxref("Document.onfullscreenerror")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("fullscreenerror")}} event is raised.</dd> + <dt>{{domxref("Document.onpaste")}} {{non-standard_inline}}</dt> + <dd>Represents the event handling code for the {{event("paste")}} event.</dd> + <dt>{{domxref("Document.onpointerlockchange")}} {{experimental_inline}}</dt> + <dd>Represents the event handling code for the {{event("pointerlockchange")}} event.</dd> + <dt>{{domxref("Document.onpointerlockerror")}} {{experimental_inline}}</dt> + <dd>Represetnts the event handling code for the {{event("pointerlockerror")}} event.</dd> + <dt>{{domxref("Document.onreadystatechange")}} {{gecko_minversion_inline("1.9.2")}}</dt> + <dd>Represents the event handling code for the {{event("readystatechange")}} event.</dd> + <dt>{{domxref("Document.onselectionchange")}} {{experimental_inline}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("selectionchange")}} event is raised.</dd> + <dt>{{domxref("Document.onwheel")}} {{non-standard_inline}}</dt> + <dd>Represents the event handling code for the {{event("wheel")}} event.</dd> +</dl> + +<p><em>此介面繼承了 {{domxref("GlobalEventHandlers")}} 的事件處理器：</em></p> + +<p>{{Page("/zh-TW/docs/Web/API/GlobalEventHandlers", "屬性")}}</p> + +<h2 id="Methods" name="Methods">方法</h2> + +<p><em>This interface also inherits from the {{domxref("Node")}} and {{domxref("EventTarget")}} interfaces.</em></p> + +<dl> + <dt>{{domxref("Document.adoptNode()")}}</dt> + <dd>Adopt node from an external document.</dd> + <dt>{{domxref("Document.captureEvents()")}} {{Deprecated_inline}}</dt> + <dd>See {{domxref("Window.captureEvents")}}.</dd> + <dt>{{domxref("Document.caretPositionFromPoint()")}}{{experimental_inline}}</dt> + <dd>Gets the {{domxref("CaretPosition")}} at or near the specified coordinates.</dd> + <dt>{{domxref("Document.caretRangeFromPoint()")}}{{non-standard_inline}}</dt> + <dd>Gets a {{Domxref("Range")}} object for the document fragment under the specified coordinates.</dd> + <dt>{{domxref("Document.createAttribute()")}}</dt> + <dd>Creates a new {{domxref("Attr")}} object and returns it.</dd> + <dt>{{domxref("Document.createAttributeNS()")}}</dt> + <dd>Creates a new attribute node in a given namespace and returns it.</dd> + <dt>{{domxref("Document.createCDATASection()")}}</dt> + <dd>Creates a new CDATA node and returns it.</dd> + <dt>{{domxref("Document.createComment()")}}</dt> + <dd>Creates a new comment node and returns it.</dd> + <dt>{{domxref("Document.createDocumentFragment()")}}</dt> + <dd>Creates a new document fragment.</dd> + <dt>{{domxref("Document.createElement()")}}</dt> + <dd>Creates a new element with the given tag name.</dd> + <dt>{{domxref("Document.createElementNS()")}}</dt> + <dd>Creates a new element with the given tag name and namespace URI.</dd> + <dt>{{domxref("Document.createEntityReference()")}} {{obsolete_inline}}</dt> + <dd>Creates a new entity reference object and returns it.</dd> + <dt>{{domxref("Document.createEvent()")}}</dt> + <dd>Creates an event object.</dd> + <dt>{{domxref("Document.createNodeIterator()")}}</dt> + <dd>Creates a {{domxref("NodeIterator")}} object.</dd> + <dt>{{domxref("Document.createProcessingInstruction()")}}</dt> + <dd>Creates a new {{domxref("ProcessingInstruction")}} object.</dd> + <dt>{{domxref("Document.createRange()")}}</dt> + <dd>Creates a {{domxref("Range")}} object.</dd> + <dt>{{domxref("Document.createTextNode()")}}</dt> + <dd>Creates a text node.</dd> + <dt>{{domxref("Document.createTouch()")}}</dt> + <dd>Creates a {{domxref("Touch")}} object.</dd> + <dt>{{domxref("Document.createTouchList()")}}</dt> + <dd>Creates a {{domxref("TouchList")}} object.</dd> + <dt>{{domxref("Document.createTreeWalker()")}}</dt> + <dd>Creates a {{domxref("TreeWalker")}} object.</dd> + <dt>{{domxref("Document.elementFromPoint()")}}{{experimental_inline}}</dt> + <dd>Returns the topmost element at the specified coordinates.</dd> + <dt>{{domxref("Document.elementsFromPoint()")}}{{experimental_inline}}</dt> + <dd>Returns an array of all elements at the specified coordinates.</dd> + <dt>{{domxref("Document.enableStyleSheetsForSet()")}}</dt> + <dd>Enables the style sheets for the specified style sheet set.</dd> + <dt>{{domxref("Document.exitPointerLock()")}} {{experimental_inline}}</dt> + <dd>Release the pointer lock.</dd> + <dt>{{domxref("Document.getAnimations()")}} {{experimental_inline}}</dt> + <dd>Returns an array of all {{domxref("Animation")}} objects currently in effect, whose target elements are descendants of the <code>document</code>.</dd> + <dt>{{domxref("Document.getElementsByClassName()")}}</dt> + <dd>Returns a list of elements with the given class name.</dd> + <dt>{{domxref("Document.getElementsByTagName()")}}</dt> + <dd>Returns a list of elements with the given tag name.</dd> + <dt>{{domxref("Document.getElementsByTagNameNS()")}}</dt> + <dd>Returns a list of elements with the given tag name and namespace.</dd> + <dt>{{domxref("Document.importNode()")}}</dt> + <dd>Returns a clone of a node from an external document.</dd> + <dt>{{domxref("Document.normalizeDocument()")}} {{obsolete_inline}}</dt> + <dd>Replaces entities, normalizes text nodes, etc.</dd> + <dt>{{domxref("Document.registerElement()")}} {{experimental_inline}}</dt> + <dd>Registers a web component.</dd> + <dt>{{domxref("Document.releaseCapture()")}} {{non-standard_inline}} {{gecko_minversion_inline("2.0")}}</dt> + <dd>Releases the current mouse capture if it's on an element in this document.</dd> + <dt>{{domxref("Document.releaseEvents()")}} {{non-standard_inline}} {{Deprecated_inline}}</dt> + <dd>See {{domxref("Window.releaseEvents()")}}.</dd> + <dt>{{domxref("Document.routeEvent()")}} {{non-standard_inline}} {{obsolete_inline(24)}}</dt> + <dd>See {{domxref("Window.routeEvent()")}}.</dd> + <dt>{{domxref("Document.mozSetImageElement()")}} {{non-standard_inline}} {{gecko_minversion_inline("2.0")}}</dt> + <dd>Allows you to change the element being used as the background image for a specified element ID.</dd> +</dl> + +<p>The <code>Document</code> interface is extended with the {{domxref("ParentNode")}} interface:</p> + +<dl> + <dt>{{domxref("document.getElementById","document.getElementById(String id)")}}</dt> + <dd>Returns an object reference to the identified element.</dd> + <dt>{{domxref("document.querySelector","document.querySelector(String selector)")}} {{gecko_minversion_inline("1.9.1")}}</dt> + <dd>Returns the first Element node within the document, in document order, that matches the specified selectors.</dd> + <dt>{{domxref("document.querySelectorAll","document.querySelectorAll(String selector)")}} {{gecko_minversion_inline("1.9.1")}}</dt> + <dd>Returns a list of all the Element nodes within the document that match the specified selectors.</dd> +</dl> + +<p>The <code>Document</code> interface is extended with the {{domxref("XPathEvaluator")}} interface:</p> + +<dl> + <dt>{{domxref("document.createExpression","document.createExpression(String expression, XPathNSResolver resolver)")}}</dt> + <dd>Compiles an <code><a href="/en-US/docs/XPathExpression" title="XPathExpression">XPathExpression</a></code> which can then be used for (repeated) evaluations.</dd> + <dt>{{domxref("document.createNSResolver","document.createNSResolver(Node resolver)")}}</dt> + <dd>Creates an {{domxref("XPathNSResolver")}} object.</dd> + <dt>{{domxref("document.evaluate","document.evaluate(String expression, Node contextNode, XPathNSResolver resolver, Number type, Object result)")}}</dt> + <dd>Evaluates an XPath expression.</dd> +</dl> + +<h3 id="HTML_文件擴充_2">HTML 文件擴充</h3> + +<p><code>Document</code> 物件的部分方法繼承自 HTML 文件的 {{domxref("HTMLDocument")}} 介面，或是來自 <code>Document</code> 從 HTML5 之後擴充的方法：</p> + +<dl> + <dt>{{domxref("document.clear()")}} {{non-standard_inline}} {{Deprecated_inline}}</dt> + <dd>In majority of modern browsers, including recent versions of Firefox and Internet Explorer, this method does nothing.</dd> + <dt>{{domxref("document.close()")}}</dt> + <dd>Closes a document stream for writing.</dd> + <dt>{{domxref("document.execCommand","document.execCommand(String command[, Boolean showUI[, String value]])")}}</dt> + <dd>On an editable document, executes a formating command.</dd> + <dt>{{domxref("document.getElementsByName","document.getElementsByName(String name)")}}</dt> + <dd>Returns a list of elements with the given name.</dd> + <dt>{{domxref("document.getSelection()")}}</dt> + <dd>Returns a {{domxref("Selection")}} object related to text selected in the document.</dd> + <dt>{{domxref("document.hasFocus()")}}</dt> + <dd>Returns <code>true</code> if the focus is currently located anywhere inside the specified document.</dd> + <dt>{{domxref("document.open()")}}</dt> + <dd>Opens a document stream for writing.</dd> + <dt>{{domxref("document.queryCommandEnabled","document.queryCommandEnabled(String command)")}}</dt> + <dd>Returns true if the formating command can be executed on the current range.</dd> + <dt>{{domxref("document.queryCommandIndeterm","document.queryCommandIndeterm(String command)")}}</dt> + <dd>Returns true if the formating command is in an indeterminate state on the current range.</dd> + <dt>{{domxref("document.queryCommandState","document.queryCommandState(String command)")}}</dt> + <dd>Returns true if the formating command has been executed on the current range.</dd> + <dt>{{domxref("document.queryCommandSupported","document.queryCommandSupported(String command)")}}</dt> + <dd>Returns true if the formating command is supported on the current range.</dd> + <dt>{{domxref("document.queryCommandValue","document.queryCommandValue(String command)")}}</dt> + <dd>Returns the current value of the current range for a formating command.</dd> + <dt>{{domxref("document.write","document.write(String text)")}}</dt> + <dd>Writes text in a document.</dd> + <dt>{{domxref("document.writeln","document.writeln(String text)")}}</dt> + <dd>Writes a line of text in a document.</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('Selection API', '', 'Extend Document and GlobalEventHandlers')}}</td> + <td>{{Spec2('Selection API')}}</td> + <td>Adds <code>onselectstart</code> and <code>onselectionchange</code>.</td> + </tr> + <tr> + <td>{{SpecName('DOM1','#i-Document','Document')}}</td> + <td>{{Spec2('DOM1')}}</td> + <td>Initial definition for the interface</td> + </tr> + <tr> + <td>{{SpecName('DOM2 Core','#i-Document','Document')}}</td> + <td>{{Spec2('DOM2 Core')}}</td> + <td>Supersede DOM 1</td> + </tr> + <tr> + <td>{{SpecName('DOM3 Core','#i-Document','Document')}}</td> + <td>{{Spec2('DOM3 Core')}}</td> + <td>Supersede DOM 2</td> + </tr> + <tr> + <td>{{SpecName('DOM WHATWG','#interface-document','Document')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>Intend to supersede DOM 3</td> + </tr> + <tr> + <td>{{SpecName('HTML WHATWG','dom.html#the-document-object','Document')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>Turn the {{domxref("HTMLDocument")}} interface into a <code>Document</code> extension.</td> + </tr> + <tr> + <td>{{SpecName('DOM3 XPath','xpath.html#XPathEvaluator','XPathEvaluator')}}</td> + <td>{{Spec2('DOM3 XPath')}}</td> + <td>Define the {{domxref("XPathEvaluator")}} interface which extend document.</td> + </tr> + <tr> + <td>{{SpecName('Page Visibility API', '#sec-document-interface', 'Document')}}</td> + <td>{{Spec2('Page Visibility API')}}</td> + <td>Extend the <code>Document</code> interface with the <code>visibilityState</code> and <code>hidden</code> attributes</td> + </tr> + <tr> + <td>{{SpecName('HTML Editing','#dom-document-getselection','Document')}}</td> + <td>{{Spec2('HTML Editing')}}</td> + <td>Extend the <code>Document</code> interface</td> + </tr> + <tr> + <td>{{SpecName('CSSOM View','#extensions-to-the-document-interface','Document')}}</td> + <td>{{Spec2('CSSOM View')}}</td> + <td>Extend the <code>Document</code> interface</td> + </tr> + <tr> + <td>{{SpecName('CSSOM','#extensions-to-the-document-interface','Document')}}</td> + <td>{{Spec2('CSSOM')}}</td> + <td>Extend the <code>Document</code> interface</td> + </tr> + <tr> + <td>{{SpecName('Pointer Lock','#extensions-to-the-document-interface','Document')}}</td> + <td>{{Spec2('Pointer Lock')}}</td> + <td>Extend the <code>Document</code> interface</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性備註">瀏覽器相容性備註</h2> + +<h3 id="Firefox_notes">Firefox notes</h3> + +<p>Mozilla defines a set of non-standard properties made only for XUL content:</p> + +<dl> + <dt>{{domxref("document.currentScript")}} {{non-standard_inline}} {{gecko_minversion_inline("2.0")}}</dt> + <dd>Returns the {{HTMLElement("script")}} element that is currently executing.</dd> + <dt>{{domxref("document.documentURIObject")}} {{gecko_minversion_inline("1.9")}}</dt> + <dd>(<strong>Mozilla add-ons only!</strong>) Returns the {{Interface("nsIURI")}} object representing the URI of the document. This property only has special meaning in privileged JavaScript code (with UniversalXPConnect privileges).</dd> + <dt>{{domxref("document.popupNode")}}</dt> + <dd>Returns the node upon which a popup was invoked.</dd> + <dt>{{domxref("document.tooltipNode")}}</dt> + <dd>Returns the node which is the target of the current tooltip.</dd> +</dl> + +<p>Mozilla also define some non-standard methods:</p> + +<dl> + <dt>{{domxref("document.execCommandShowHelp")}} {{obsolete_inline("14.0")}}</dt> + <dd>This method never did anything and always threw an exception, so it was removed in Gecko 14.0 {{geckoRelease("14.0")}}.</dd> + <dt>{{domxref("document.getBoxObjectFor")}} {{obsolete_inline}}</dt> + <dd>Use the {{domxref("Element.getBoundingClientRect()")}} method instead.</dd> + <dt>{{domxref("document.loadOverlay")}} {{Fx_minversion_inline("1.5")}}</dt> + <dd>Loads a <a href="/en-US/docs/XUL_Overlays" title="XUL_Overlays">XUL overlay</a> dynamically. This only works in XUL documents.</dd> + <dt>{{domxref("document.queryCommandText")}} {{obsolete_inline("14.0")}}</dt> + <dd>This method never did anything but throw an exception, and was removed in Gecko 14.0 {{geckoRelease("14.0")}}.</dd> +</dl> + +<h3 id="Internet_Explorer_notes">Internet Explorer notes</h3> + +<p>Microsoft defines some non-standard properties:</p> + +<dl> + <dt>{{domxref("document.fileSize")}}* {{non-standard_inline}} {{obsolete_inline}}</dt> + <dd>Returns size in bytes of the document. Starting with Internet Explorer 11, that property is no longer supported. See <a href="http://msdn.microsoft.com/en-us/library/ms533752%28v=VS.85%29.aspx" title="http://msdn.microsoft.com/en-us/library/ms533752%28v=VS.85%29.aspx">MSDN</a>.</dd> + <dt><span style="font-weight: normal; line-height: 1.5;">Internet Explorer does not support all methods from the <code>Node</code> interface in the <code>Document</code> interface:</span></dt> +</dl> + +<dl> + <dt>{{domxref("document.contains")}}</dt> + <dd>As a work-around, <code>document.body.contains()</code> can be used.</dd> +</dl> diff --git a/files/zh-tw/web/api/document/keyup_event/index.html b/files/zh-tw/web/api/document/keyup_event/index.html new file mode 100644 index 0000000000..3568b30c18 --- /dev/null +++ b/files/zh-tw/web/api/document/keyup_event/index.html @@ -0,0 +1,149 @@ +--- +title: keyup +slug: Web/API/Document/keyup_event +translation_of: Web/API/Document/keyup_event +--- +<p>當鍵盤上的手指離開按鍵時，<code>keyup事件會被觸發。</code></p> + +<h2 id="基本資料">基本資料</h2> + +<dl> + <dt style="float: left; text-align: right; width: 120px;">詳述</dt> + <dd style="margin: 0 0 0 120px;"><a class="external" href="http://www.w3.org/TR/DOM-Level-3-Events/#event-type-keyup">DOM L3</a></dd> + <dt style="float: left; text-align: right; width: 120px;">介面</dt> + <dd style="margin: 0 0 0 120px;"><a href="http://developer.mozilla.org/en-US/docs/DOM/KeyboardEvent" title="http://en-US/docs/DOM/KeyboardEvent">KeyboardEvent</a></dd> + <dt style="float: left; text-align: right; width: 120px;">Bubbles</dt> + <dd style="margin: 0 0 0 120px;">Yes</dd> + <dt style="float: left; text-align: right; width: 120px;">Cancelable</dt> + <dd style="margin: 0 0 0 120px;">Yes</dd> + <dt style="float: left; text-align: right; width: 120px;">Target</dt> + <dd style="margin: 0 0 0 120px;">網頁文件, 網頁元素</dd> + <dt style="float: left; text-align: right; width: 120px;">Default Action</dt> + <dd style="margin: 0 0 0 120px;">None</dd> +</dl> + +<h2 id="屬性">屬性</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Property</th> + <th scope="col">Type</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>target</code> {{readonlyInline}}</td> + <td>EventTarget</td> + <td>The event target (the topmost target in the DOM tree).</td> + </tr> + <tr> + <td><code>type</code> {{readonlyInline}}</td> + <td>DOMString</td> + <td>The type of event.</td> + </tr> + <tr> + <td><code>bubbles</code> {{readonlyInline}}</td> + <td>Boolean</td> + <td>Whether the event normally bubbles or not</td> + </tr> + <tr> + <td><code>cancelable</code> {{readonlyInline}}</td> + <td>Boolean</td> + <td>Whether the event is cancellable or not?</td> + </tr> + <tr> + <td><code>view</code> {{readonlyInline}}</td> + <td>WindowProxy</td> + <td><a href="/en-US/docs/Web/API/Document/defaultView" title="In browsers, document.defaultView returns the window object associated with a document, or null if none is available."><code>document.defaultView</code></a> (<code>window</code> of the document)</td> + </tr> + <tr> + <td><code>detail</code> {{readonlyInline}}</td> + <td><code>long</code> (<code>float</code>)</td> + <td>0.</td> + </tr> + <tr> + <td><code>target</code> {{readonlyInline}}</td> + <td>EventTarget (DOM element)</td> + <td>Focused element processing the key event, root element if no suitable input element focused.</td> + </tr> + <tr> + <td><code>char</code> {{readonlyInline}}</td> + <td>DOMString (string)</td> + <td>The character value of the key. If the key corresponds to a printable character, this value is a non-empty Unicode string containing that character. If the key doesn't have a printable representation, this is an empty string. See <a href="/en-US/docs/Web/API/KeyboardEvent#Key_names_and_Char_values">key names and char values</a> for the detail. + <div class="note"><strong>Note:</strong> If the key is used as a macro that inserts multiple characters, this attribute's value is the entire string, not just the first character.</div> + </td> + </tr> + <tr> + <td><code>key</code> {{readonlyInline}}</td> + <td>DOMString (string)</td> + <td>The key value of the key represented by the event. If the value has a printed representation, this attribute's value is the same as the <code>char</code> attribute. Otherwise, it's one of the key value strings specified in {{ anch("Key values") }}. If the key can't be identified, this is the string "Unidentified". See <a href="/en-US/docs/Web/API/KeyboardEvent#Key_names_and_Char_values">key names and char values</a> for the detail. Read Only.</td> + </tr> + <tr> + <td><code>charCode</code> {{readonlyInline}}</td> + <td>Unsigned long (int)</td> + <td>The Unicode reference number of the key; this attribute is used only by the <a href="/en-US/docs/Mozilla_event_reference/keypress"><code>keypress</code></a> event. For keys whose <code>char</code> attribute contains multiple characters, this is the Unicode value of the first character in that attribute. + <div class="warning"><strong>Warning:</strong> This attribute is deprecated; you should use <code>char</code> instead, if available.</div> + </td> + </tr> + <tr> + <td><code>keyCode</code> {{readonlyInline}}</td> + <td>Unsigned long (int)</td> + <td>A system and implementation dependent numerical code identifying the unmodified value of the pressed key. This is usually the decimal ASCII ({{ RFC(20) }}) or Windows 1252 code corresponding to the key; see {{ anch("Virtual key codes") }} for a list of common values. If the key can't be identified, this value is 0. + <div class="warning"><strong>Warning:</strong> This attribute is deprecated; you should use <code>key</code> instead, if available.</div> + </td> + </tr> + <tr> + <td><code>which</code> {{readonlyInline}}</td> + <td>Unsigned long (int)</td> + <td>A system and implementation dependent numeric code identifying the unmodified value of the pressed key; this is usually the same as <code>keyCode</code>. + <div class="warning"><strong>Warning:</strong> This attribute is deprecated; you should use <code>key</code> instead, if available.</div> + </td> + </tr> + <tr> + <td><code>location</code> {{readonlyInline}}</td> + <td>long (float)</td> + <td>The location of the key on the device.</td> + </tr> + <tr> + <td><code>repeat</code> {{readonlyInline}}</td> + <td>boolean</td> + <td><code>true</code> if a key has been depressed long enough to trigger key repetition, otherwise <code>false</code>.</td> + </tr> + <tr> + <td><code>locale</code> {{readonlyInline}}</td> + <td>string</td> + <td>The language code for the key event, if available; otherwise, the empty string.</td> + </tr> + <tr> + <td><code>ctrlKey</code> {{readonlyInline}}</td> + <td>boolean</td> + <td><code>true</code> if the control key was down when the event was fired. <code>false</code> otherwise.</td> + </tr> + <tr> + <td><code>shiftKey</code> {{readonlyInline}}</td> + <td>boolean</td> + <td><code>true</code> if the shift key was down when the event was fired. <code>false</code> otherwise.</td> + </tr> + <tr> + <td><code>altKey</code> {{readonlyInline}}</td> + <td>boolean</td> + <td><code>true</code> if the alt key was down when the event was fired. <code>false</code> otherwise.</td> + </tr> + <tr> + <td><code>metaKey</code> {{readonlyInline}}</td> + <td>boolean</td> + <td><code>true</code> if the meta key was down when the event was fired. <code>false</code> otherwise.</td> + </tr> + </tbody> +</table> + +<h2 id="Related_Events">Related Events</h2> + +<ul> + <li>{{event("keydown")}}</li> + <li>{{event("keyup")}}</li> + <li>{{event("keypress")}}</li> + <li>{{event("input")}}</li> +</ul> diff --git a/files/zh-tw/web/api/document/queryselector/index.html b/files/zh-tw/web/api/document/queryselector/index.html new file mode 100644 index 0000000000..a79edb1c1f --- /dev/null +++ b/files/zh-tw/web/api/document/queryselector/index.html @@ -0,0 +1,102 @@ +--- +title: document.querySelector +slug: Web/API/Document/querySelector +tags: + - DOM + - Fixit + - Gecko DOM Reference + - Gecko DOM 參考 + - Selectors + - 選擇器 +translation_of: Web/API/Document/querySelector +--- +<div> + {{ApiRef()}}</div> +<h2 id="Summary" name="Summary">摘要</h2> +<p>回傳 document 第一個符合特定選擇器群組的元素（採用深度優先，前序追蹤 document 節點）。</p> +<h2 id="Syntax" name="Syntax">語法</h2> +<pre><em>element</em> = document.querySelector(<em>selectors</em>);</pre> +<p>其中</p> +<ul> + <li><code>element</code> 是<a href="/en-US/docs/DOM/element" title="en-US/docs/DOM/element">元素</a>物件。</li> + <li><code>selectors</code> 是以逗號分隔，包含一個或多個 CSS 選擇器的字串。</li> +</ul> +<h2 id="Example" name="Example">範例</h2> +<p>這個範例會回傳 document 選到的第一個 "<code>myclass</code>" class：</p> +<pre class="brush: js">var el = document.querySelector(".myclass"); +</pre> +<h2 id="Notes" name="Notes">注意事項</h2> +<p>若找不到相應元素就會回傳 <code>null</code>，否則回傳第一個符合的元素。</p> +<p>若選擇器符合某 ID，且該 ID 在 document 中誤用數次，就會回傳第一個符合的元素。</p> +<p>當特定選擇器群組無效，會擲回 <code>SYNTAX_ERR</code> 例外狀況。</p> +<p><code>querySelector()</code> 是由 Selectors API 引入的選擇器。</p> +<p>傳入 <code>querySelector</code> 的字串參數必須遵循 CSS 語法。若要選取未遵循 CSS 語法的 ID 或選擇器（例如不當使用冒號或空格），必須強制加上兩個反斜線來跳脫錯誤的字元：</p> +<pre class="brush: html"><div id="foo\bar"></div> +<div id="foo:bar"></div> + +<script> +document.querySelector('#foo\bar') // 甚麼都沒選到 +document.querySelector('#foo\\\\bar') // 選到第一個 div +document.querySelector('#foo:bar') // 甚麼都沒選到 +document.querySelector('#foo\\:bar') // 選到第二個 div +</script> +</pre> +<h2 id="Browser_Compatibility" name="Browser_Compatibility">瀏覽器相容性</h2> +<p>{{CompatibilityTable()}}</p> +<div id="compat-desktop"> + <table class="compat-table"> + <tbody> + <tr> + <th>功能特色</th> + <th>Chrome</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari (WebKit)</th> + </tr> + <tr> + <td>基本支援</td> + <td>1</td> + <td>3.5 (1.9.1)<br> + {{bug(416317)}}</td> + <td>8</td> + <td>10</td> + <td>3.2 (525.3)<br> + {{Webkitbug("16587")}}</td> + </tr> + </tbody> + </table> +</div> +<div id="compat-mobile"> + <table class="compat-table"> + <tbody> + <tr> + <th>功能特色</th> + <th>Android</th> + <th>Firefox 行動版 (Gecko)</th> + <th>IE 行動版</th> + <th>Opera 行動版</th> + <th>Safari 行動版</th> + </tr> + <tr> + <td>基本支援</td> + <td>2.1</td> + <td>有</td> + <td>9</td> + <td>10.0</td> + <td>3.2</td> + </tr> + </tbody> + </table> +</div> +<h2 id="Specification" name="Specification">規格文件</h2> +<ul> + <li><a class="external" href="http://www.w3.org/TR/selectors-api/" title="http://www.w3.org/TR/selectors-api/">Selectors API</a></li> +</ul> +<h2 id="See_also" name="See_also">詳見</h2> +<ul> + <li>{{domxref("document.querySelectorAll()")}}</li> + <li>{{domxref("element.querySelector()")}}</li> + <li>{{domxref("element.querySelectorAll()")}}</li> + <li><a href="/en-US/docs/Code_snippets/QuerySelector" title="en-US/docs/Code snippets/QuerySelector">querySelector 代碼片段</a></li> +</ul> diff --git a/files/zh-tw/web/api/document/readystate/index.html b/files/zh-tw/web/api/document/readystate/index.html new file mode 100644 index 0000000000..13cf835aa7 --- /dev/null +++ b/files/zh-tw/web/api/document/readystate/index.html @@ -0,0 +1,108 @@ +--- +title: Document.readyState +slug: Web/API/Document/readyState +tags: + - API + - HTML DOM + - Reference +translation_of: Web/API/Document/readyState +--- +<div>{{APIRef("DOM")}} {{ gecko_minversion_header("1.9.2") }}</div> + +<h2 id="Summary" name="Summary">總覽</h2> + +<p>{{ domxref("document") }} 的 <strong>Document.readyState</strong> 屬性描述文件的讀取狀態。</p> + +<h3 id="數值">數值</h3> + +<p>文件的 <strong>readyState</strong> 數值如下：</p> + +<dl> + <dt>loading</dt> + <dd>{{ domxref("document") }} 正在讀取中。</dd> + <dt>interactive</dt> + <dd>文件已經完成讀取和解析，但是其他的子資源，如「圖片樣式層次表」，仍然在讀取。這個狀態表示 {{event("DOMContentLoaded")}} 事件已經被觸發。</dd> + <dt>complete</dt> + <dd>文件及子資源都完成讀取。這個狀態表示 {{event("load")}} 事件即將被觸發。</dd> +</dl> + +<p>當這個屬性的數值改變時， {{event("readystatechange")}} 事件在 {{ domxref("document") }} 上觸發。</p> + +<h2 id="表達式">表達式</h2> + +<pre class="brush: js"><em>var string</em> = document.readyState; +</pre> + +<h2 id="範例"><span>範例</span></h2> + +<h3 id="不同的狀態">不同的狀態</h3> + +<pre class="brush: js"><span>switch (document.readyState) { + case "loading": + // 文件讀取中。 + break; + case "interactive": + // 文件已經完成讀取。可以使用 DOM 元素。 + var span = document.createElement("span"); + span.textContent = "A <span> element."; + document.body.appendChild(span); + break; + case "complete": + // 頁面已經完成讀取。 + console.log("The first CSS rule is: " + document.styleSheets[0].cssRules[0].cssText); + break; +}</span> +</pre> + +<h3 id="readystatechange_替代_DOMContentLoaded">readystatechange 替代 DOMContentLoaded</h3> + +<pre class="brush:js">// alternative to DOMContentLoaded event +document.onreadystatechange = function () { + if (document.readyState == "interactive") { + initApplication(); + } +}</pre> + +<h3 id="readystatechange_替代_load">readystatechange 替代 load</h3> + +<pre class="brush: js">// alternative to load event +document.onreadystatechange = function () { + if (document.readyState == "complete") { + initApplication(); + } +}</pre> + +<h2 id="規範">規範</h2> + +<table class="spectable standard-table"> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">註</th> + </tr> + <tr> + <td>{{SpecName("HTML WHATWG", "#current-document-readiness", "Document readiness")}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("HTML5.1", "#current-document-readiness", "Document readiness")}}</td> + <td>{{Spec2('HTML5.1')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("HTML5 W3C", "#current-document-readiness", "Document readiness")}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{event("readystatechange")}} event</li> + <li>{{event("DOMContentLoaded")}} event</li> + <li>{{event("load")}} event</li> +</ul> diff --git a/files/zh-tw/web/api/document/registerelement/index.html b/files/zh-tw/web/api/document/registerelement/index.html new file mode 100644 index 0000000000..66c3330dca --- /dev/null +++ b/files/zh-tw/web/api/document/registerelement/index.html @@ -0,0 +1,113 @@ +--- +title: Document.registerElement() +slug: Web/API/Document/registerElement +tags: + - API + - DOM + - JavaScript + - 自訂標籤 +translation_of: Web/API/Document/registerElement +--- +<p>{{APIRef("DOM")}}{{Deprecated_header}}</p> + +<div class="warning"> +<p><strong>Warning: </strong>document.registerElement() 已經被棄用，建議使用 <a href="/en-US/docs/Web/API/CustomElementRegistry/define">customElements.define()</a>.</p> +</div> + +<p>{{draft}}</p> + +<p> <code><strong>document.registerElement()</strong></code> 可以在瀏覽器中註冊一個新的自訂標籤(元素)and returns a constructor for the new element.</p> + +<div class="note"> +<p><strong>Note:</strong> This is an experimental technology. The browser you use it in must support Web Components. See <a href="/en-US/docs/Web/Web_Components#Enabling_Web_Components_in_Firefox">Enabling Web Components in Firefox</a>.</p> +</div> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">var <em>constructor</em> = document.registerElement(<em>tag-name</em>, <em>options</em>);</pre> + +<h3 id="參數">參數</h3> + +<dl> + <dt><em>標籤名稱</em></dt> + <dd>自訂的標籤名稱需有一個 橫線 ( - ), 例如<code>my-tag</code>.</dd> + <dt><em>options {{optional_inline}}</em></dt> + <dd> + <p>An object with properties <strong>prototype</strong> to base the custom element on, and <strong>extends</strong>, an existing tag to extend. Both of these are optional.</p> + </dd> +</dl> + +<h2 id="例子">例子</h2> + +<p>這是一個非常簡單的例子:</p> + +<pre class="brush: js">var Mytag = document.registerElement('my-tag'); +</pre> + +<p>現在新的標籤已經在瀏覽器中註冊了. The <code>Mytag</code> variable holds a constructor that you can use to create a <code>my-tag</code> element in the document as follows:</p> + +<pre class="brush: js">document.body.appendChild(new Mytag());</pre> + +<p>This inserts an empty <code>my-tag</code> element that will be visible if you use the browser's developer tools. It will not be visible if you use the browser's view source capability. And it won't be visible in the browser unless you add some content to the tag. Here is one way to add content to the new tag:</p> + +<pre class="brush: js">var mytag = document.getElementsByTagName("my-tag")[0]; +mytag.textContent = "I am a my-tag element."; +</pre> + +<h2 id="瀏覽器支援性">瀏覽器支援性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>35</td> + <td>31<sup>[1]</sup></td> + <td>{{CompatNo}}</td> + <td>25</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>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>4.4.4</td> + <td>31<sup>[1]</sup></td> + <td>{{CompatNo}}</td> + <td>25</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] This API is implemented behind a preference.</p> + +<h2 id="也看一下">也看一下</h2> + +<ul> + <li><a dir="ltr" href="/en-US/docs/Web/Web_Components/Custom_Elements">Custom Elements</a></li> +</ul> diff --git a/files/zh-tw/web/api/document/scroll_event/index.html b/files/zh-tw/web/api/document/scroll_event/index.html new file mode 100644 index 0000000000..26dbb7640c --- /dev/null +++ b/files/zh-tw/web/api/document/scroll_event/index.html @@ -0,0 +1,103 @@ +--- +title: scroll +slug: Web/API/Document/scroll_event +translation_of: Web/API/Document/scroll_event +--- +<p>當文件的可視區或元素被滾動(scroll)，<code>scroll</code>事件會被觸發</p> + +<h2 id="一般資訊">一般資訊</h2> + +<dl> + <dt style="float: left; text-align: right; width: 120px;">規範</dt> + <dd style="margin: 0 0 0 120px;"><a class="external" href="http://www.w3.org/TR/DOM-Level-3-Events/#event-type-scroll">DOM L3</a>, <a href="http://www.w3.org/TR/cssom-view/#scrolling-0">CSSOM View</a></dd> + <dt style="float: left; text-align: right; width: 120px;">介面</dt> + <dd style="margin: 0 0 0 120px;">UIEvent</dd> + <dt style="float: left; text-align: right; width: 120px;">Bubbles</dt> + <dd style="margin: 0 0 0 120px;">Not on elements, but bubbles to the default view when fired on the document</dd> + <dt style="float: left; text-align: right; width: 120px;">Cancelable</dt> + <dd style="margin: 0 0 0 120px;">No</dd> + <dt style="float: left; text-align: right; width: 120px;">Target</dt> + <dd style="margin: 0 0 0 120px;">defaultView, Document, Element</dd> + <dt style="float: left; text-align: right; width: 120px;">Default Action</dt> + <dd style="margin: 0 0 0 120px;">None</dd> +</dl> + +<h2 id="屬性">屬性</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Property</th> + <th scope="col">Type</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>target</code> {{readonlyInline}}</td> + <td><a href="/en-US/docs/Web/API/EventTarget" title="EventTarget is an interface implemented by objects that can receive events and may have listeners for them."><code>EventTarget</code></a></td> + <td>The event target (the topmost target in the DOM tree).</td> + </tr> + <tr> + <td><code>type</code> {{readonlyInline}}</td> + <td><a href="/en-US/docs/Web/API/DOMString" title="DOMString is a UTF-16 String. As JavaScript already uses such strings, DOMString is mapped directly to a String."><code>DOMString</code></a></td> + <td>The type of event.</td> + </tr> + <tr> + <td><code>bubbles</code> {{readonlyInline}}</td> + <td><a href="/en-US/docs/Web/API/Boolean" title="The Boolean object is an object wrapper for a boolean value."><code>Boolean</code></a></td> + <td>Whether the event normally bubbles or not.</td> + </tr> + <tr> + <td><code>cancelable</code> {{readonlyInline}}</td> + <td><a href="/en-US/docs/Web/API/Boolean" title="The Boolean object is an object wrapper for a boolean value."><code>Boolean</code></a></td> + <td>Whether the event is cancellable or not.</td> + </tr> + <tr> + <td><code>view</code> {{readonlyInline}}</td> + <td><a class="new" href="/en-US/docs/Web/API/WindowProxy" rel="nofollow" title="The documentation about this has not yet been written; please consider contributing!"><code>WindowProxy</code></a></td> + <td><a href="/en-US/docs/Web/API/Document/defaultView" title="In browsers, document.defaultView returns the window object associated with a document, or null if none is available."><code>document.defaultView</code></a> (<code>window</code> of the document)</td> + </tr> + <tr> + <td><code>detail</code> {{readonlyInline}}</td> + <td><code>long</code> (<code>float</code>)</td> + <td>0.</td> + </tr> + </tbody> +</table> + +<h2 id="Example">Example</h2> + +<p>因為 <code>scroll</code> 事件是高頻觸發，這樣的事件處理程式不該進行運算成本高的程式，像是DOM的修改。所以，建議使用 <a href="/en-US/docs/DOM/window.requestAnimationFrame" title="/en-US/docs/DOM/window.requestAnimationFrame">requestAnimationFrame</a>, <a href="/en-US/docs/Web/API/WindowTimers/setTimeout">setTimeout</a> 或 <a href="/en-US/docs/Web/API/CustomEvent">customEvent</a> 如下所示</p> + +<h4 id="Scroll_optimization_with_window.requestAnimationFrame">Scroll optimization with window.requestAnimationFrame</h4> + +<pre class="brush: js">// Reference: http://www.html5rocks.com/en/tutorials/speed/animations/ + +var last_known_scroll_position = 0; +var ticking = false; + +function doSomething(scroll_pos) { + // do something with the scroll position +} + +window.addEventListener('scroll', function(e) { + last_known_scroll_position = window.scrollY; + if (!ticking) { + window.requestAnimationFrame(function() { + doSomething(last_known_scroll_position); + ticking = false; + }); + } + ticking = true; +});</pre> + +<p> </p> + +<p>關於<a href="/en-US/docs/Web/Events/resize#Example">resize</a>事件的更多類似例子。</p> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<h3 id="iOS_UIWebView">iOS UIWebView</h3> + +<p>在iOS UIWebViews中，滾動捲軸時 <code>scroll </code>事件不會觸發；它們要等到滾動完成時才被觸發。請參閱<a href="https://github.com/twbs/bootstrap/issues/16202">Bootstrap issue #16202</a>。 Safari 和 WKWebViews 不受此bug的影響。</p> diff --git a/files/zh-tw/web/api/document/width/index.html b/files/zh-tw/web/api/document/width/index.html new file mode 100644 index 0000000000..39eef5c184 --- /dev/null +++ b/files/zh-tw/web/api/document/width/index.html @@ -0,0 +1,45 @@ +--- +title: Document.width +slug: Web/API/Document/width +translation_of: Web/API/Document/width +--- +<div>{{APIRef("DOM")}} {{Obsolete_header}}</div> + +<div class="note"> +<p><strong>注意:</strong> 從 {{Gecko("6.0")}} 開始， <code>document.width 將不再被支援。取而代之的是 </code><code>document.body.clientWidth 。請參照： </code>{{domxref("element.clientWidth")}}.</p> +</div> + +<p>傳回目前文件中，{{HTMLElement("body")}} 元素的寬度有多少像素。</p> + +<p>Internet Explorer 不支援！</p> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox"><em>pixels</em> = document.width; +</pre> + +<h2 id="Example" name="Example">範例</h2> + +<pre class="brush:js">function init() { + alert("文件的寬度是 " + document.width + " 像素。"); +} +</pre> + +<h2 id="Alternatives" name="Alternatives">其他替代</h2> + +<pre class="syntaxbox">document.body.clientWidth /* <body> 的寬度 */ +document.documentElement.clientWidth /* <html> 的寬度 */ +window.innerWidth /* 視窗的寬度 */ +</pre> + +<h2 id="Specification" name="Specification">規範於</h2> + +<p>HTML5</p> + +<h2 id="See_also" name="See_also">同時參考</h2> + +<ul> + <li>{{domxref("document.height")}}</li> + <li>{{domxref("Element.clientWidth")}}</li> + <li>{{domxref("Element.scrollWidth")}}</li> +</ul> diff --git a/files/zh-tw/web/api/document_object_model/examples/index.html b/files/zh-tw/web/api/document_object_model/examples/index.html new file mode 100644 index 0000000000..66a1756da6 --- /dev/null +++ b/files/zh-tw/web/api/document_object_model/examples/index.html @@ -0,0 +1,373 @@ +--- +title: 使用 web 和 XML 開發來使用 DOM +slug: Web/API/Document_Object_Model/Examples +translation_of: Web/API/Document_Object_Model/Examples +--- +<p>本章介紹了使用 DOM 進行 Web 以及 XML 開發的一些長範例。只要可能，在例子就會使用通用的 JavaScript Web API 、技巧以及模式來操作文檔對象（the document object）。</p> + +<h2 id="Example_1:_height_and_width" name="Example_1:_height_and_width">範例一：高度和寬度</h2> + +<p>下面的例子展示了在不同尺寸的圖片時使用其高（height）和寬（width）屬性的情況：</p> + +<pre class="brush:html"><!DOCTYPE html> +<html lang="en"> +<head> +<title>width/height example</title> +<script> +function init() { + var arrImages = new Array(3); + + arrImages[0] = document.getElementById("image1"); + arrImages[1] = document.getElementById("image2"); + arrImages[2] = document.getElementById("image3"); + + var objOutput = document.getElementById("output"); + var strHtml = "<ul>"; + + for (var i = 0; i < arrImages.length; i++) { + strHtml += "<li>image" + (i+1) + + ": height=" + arrImages[i].height + + ", width=" + arrImages[i].width + + ", style.height=" + arrImages[i].style.height + + ", style.width=" + arrImages[i].style.width + + "<\/li>"; + } + + strHtml += "<\/ul>"; + + objOutput.innerHTML = strHtml; +} +</script> +</head> +<body onload="init();"> + +<p>Image 1: no height, width, or style + <img id="image1" src="http://www.mozilla.org/images/mozilla-banner.gif"> +</p> + +<p>Image 2: height="50", width="500", but no style + <img id="image2" + src="http://www.mozilla.org/images/mozilla-banner.gif" + height="50" width="500"> +</p> + +<p>Image 3: no height, width, but style="height: 50px; width: 500px;" + <img id="image3" + src="http://www.mozilla.org/images/mozilla-banner.gif" + style="height: 50px; width: 500px;"> +</p> + +<div id="output"> </div> +</body> +</html> +</pre> + +<h2 id="Example_2:_Image_Attributes" name="Example_2:_Image_Attributes">範例二：圖片屬性</h2> + +<pre class="brush:html"><!DOCTYPE html> +<html lang="en"> +<head> +<title>Modifying an image border</title> + +<script> +function setBorderWidth(width) { + document.getElementById("img1").style.borderWidth = width + "px"; +} +</script> +</head> + +<body> +<p> + <img id="img1" + src="image1.gif" + style="border: 5px solid green;" + width="100" height="100" alt="border test"> +</p> + +<form name="FormName"> + <input type="button" value="Make border 20px-wide" onclick="setBorderWidth(20);" /> + <input type="button" value="Make border 5px-wide" onclick="setBorderWidth(5);" /> +</form> + +</body> +</html> +</pre> + +<h2 id="Example_3:_Manipulating_Styles" name="Example_3:_Manipulating_Styles">範例三：改變樣式（style）</h2> + +<p>在下面這個簡單的例子中，透過取得的 DOM 元素中的 style 物件和 style 物件中的屬性，我們可以取得 HTML 段落中的一些基本樣式屬性。在本例中，你可以直接操控各別的樣式屬性。在下一個的例子裡（見例4），你可以使用 stylesheets 和它的規則來改變整個文檔的樣式。</p> + +<pre class="brush:html"><!DOCTYPE html> +<html lang="en"> +<head> +<title>Changing color and font-size example</title> + +<script> +function changeText() { + var p = document.getElementById("pid"); + + p.style.color = "blue" + p.style.fontSize = "18pt" +} +</script> +</head> +<body> + +<p id="pid" onclick="window.location.href = 'http://www.cnn.com/';">linker</p> + +<form> + <p><input value="rec" type="button" onclick="changeText();" /></p> +</form> + +</body> +</html> +</pre> + +<h2 id="Example_4:_Using_Stylesheets" name="Example_4:_Using_Stylesheets">範例四：使用樣式表（stylesheets）</h2> + +<p>在文檔物件的 styleSheets 屬性會回傳一系列載入文檔中的樣式表（stylesheets）。你可以透過 styleSheets、style 和 CSSRule 物件來獲取樣式表和每條樣式規則。在下面的例子中，把所有的樣式規則中的選擇器文本（字符串）打印到控制台中。</p> + +<pre class="brush:js">var ss = document.styleSheets; + +for(var i = 0; i < ss.length; i++) { + for(var j = 0; j < ss[i].cssRules.length; j++) { + dump( ss[i].cssRules[j].selectorText + "\n" ); + } +}</pre> + +<p>下面是一個只定義了三條樣式規則的單一樣式表的文檔：</p> + +<pre class="brush:css">body { background-color: darkblue; } +p { font-face: Arial; font-size: 10pt; margin-left: .125in; } +#lumpy { display: none; } +</pre> + +<p>該腳本會輸出如下的結果：</p> + +<pre>BODY +P +#LUMPY +</pre> + +<h2 id="Example_5:_Event_Propagation" name="Example_5:_Event_Propagation">範例五：事件傳遞</h2> + +<p>本例以一種簡單的方法闡述了事件是如何觸發以及在 DOM 中是如何處理的。當這個 HTML 文檔 BODY 載入的時候，在表格的首行註冊了一個事件監聽器。事件監聽器透過執行函數 stopEvent 來處理事件，從而改變在該表格底部的值。</p> + +<p>然而，stopEvent 同時也會另外執行一個事件物件的方法{{domxref("event.stopPropagation")}}，這會使得該事件（點擊）無法在 DOM 中有進一步的冒泡行為。請注意，表格本身有一個 {{domxref("element.onclick","onclick")}} 事件，使得這個表格被點擊時的時候原本應該要會跳出一個訊息。但因為 stopEvent 方法已經阻止了冒泡，所以在表格中的數據更新後，該事件階段有效地結束，表格的點擊事件沒有被觸發，而是顯示一個警告框（event propagation halted）——證實了事件被有效結束而沒有進一步冒泡。</p> + +<pre class="brush:html"><!DOCTYPE html> +<html lang="en"> +<head> +<title>Event Propagation</title> + +<style> +#t-daddy { border: 1px solid red } +#c1 { background-color: pink; } +</style> + +<script> +function stopEvent(ev) { + c2 = document.getElementById("c2"); + c2.innerHTML = "hello"; + + // this ought to keep t-daddy from getting the click. + ev.stopPropagation(); + alert("event propagation halted."); +} + +function load() { + elem = document.getElementById("tbl1"); + elem.addEventListener("click", stopEvent, false); +} +</script> +</head> + +<body onload="load();"> + +<table id="t-daddy" onclick="alert('hi');"> + <tr id="tbl1"> + <td id="c1">one</td> + </tr> + <tr> + <td id="c2">two</td> + </tr> +</table> + +</body> +</html> +</pre> + +<h2 id="Example_6:_getComputedStyle" name="Example_6:_getComputedStyle">Example 6: getComputedStyle</h2> + +<p>這個例子演示了如何用 {{domxref("window.getComputedStyle")}} 方法來獲取一個尚未被透過樣式元素或 JavaScript 設定的元素樣式（例如，elt.style.backgroundColor="RGB(173，216，230)"）。列舉在 {{domxref("element.style", "elt.style")}} 後面的類型的樣式可以用更直接{{domxref("element.style", "elt.style")}} 屬性獲取。</p> + +<p><code>getComputedStyle() 返回了一個 ComputedCSSStyleDeclaration 物件，其獨立的樣式屬性可以用該物件的 getPropertyValue() 方法引用，如同下面的例子一樣：</code></p> + +<pre class="brush:html"><!DOCTYPE html> +<html lang="en"> +<head> + +<title>getComputedStyle example</title> + +<script> +function cStyles() { + var RefDiv = document.getElementById("d1"); + var txtHeight = document.getElementById("t1"); + var h_style = document.defaultView.getComputedStyle(RefDiv, null).getPropertyValue("height"); + + txtHeight.value = h_style; + + var txtWidth = document.getElementById("t2"); + var w_style = document.defaultView.getComputedStyle(RefDiv, null).getPropertyValue("width"); + + txtWidth.value = w_style; + + var txtBackgroundColor = document.getElementById("t3"); + var b_style = document.defaultView.getComputedStyle(RefDiv, null).getPropertyValue("background-color"); + + txtBackgroundColor.value = b_style; +} +</script> + +<style> +#d1 { + margin-left: 10px; + background-color: rgb(173, 216, 230); + height: 20px; + max-width: 20px; +} +</style> + +</head> + +<body> + +<div id="d1">&nbsp;</div> + +<form action=""> + <p> + <button type="button" onclick="cStyles();">getComputedStyle</button> + height<input id="t1" type="text" value="1" /> + max-width<input id="t2" type="text" value="2" /> + bg-color<input id="t3" type="text" value="3" /> + </p> +</form> + +</body> +</html> +</pre> + +<h2 id="Example_7:_Displaying_Event_Object_Properties" name="Example_7:_Displaying_Event_Object_Properties">範例七：顯示事件物件的屬性</h2> + +<p>這個例子使用 DOM 方法來顯示所有 {{domxref("window.onload")}} {{domxref("event")}} 物件的屬性及其在 table 中的值。這個方法也展示一個有用的技術，使用 for...in 迴圈來來遍歷一個物件的屬性，以得到它們的值。</p> + +<p>不同瀏覽器之間事件物件的屬性有很大不同，<a href="https://dom.spec.whatwg.org">WHATWG DOM Standard</a> 規範了事件的標準屬性，然而，許多瀏覽器都大大擴展了這些。</p> + +<p>將下面的代碼放到一個空白的文本文件，並將其用各種瀏覽器開啟，你一定會對各種瀏覽器之間的不一致（事件屬性的名稱及其數量）感到驚訝。你可能還喜歡在這個頁面加入一些元素，並呼叫不同的事件處理函數（event handlers）。</p> + +<pre class="brush:html"><!DOCTYPE html> +<html lang="en"> +<head> +<meta charset="utf-8"/> +<title>Show Event properties</title> + +<style> +table { border-collapse: collapse; } +thead { font-weight: bold; } +td { padding: 2px 10px 2px 10px; } + +.odd { background-color: #efdfef; } +.even { background-color: #ffffff; } +</style> + +<script> + +function showEventProperties(e) { + function addCell(row, text) { + var cell = row.insertCell(-1); + cell.appendChild(document.createTextNode(text)); + } + + var e = e || window.event; + document.getElementById('eventType').innerHTML = e.type; + + var table = document.createElement('table'); + var thead = table.createTHead(); + var row = thead.insertRow(-1); + var lableList = ['#', 'Property', 'Value']; + var len = lableList.length; + + for (var i=0; i<len; i++) { + addCell(row, lableList[i]); + } + + var tbody = document.createElement('tbody'); + table.appendChild(tbody); + + for (var p in e) { + row = tbody.insertRow(-1); + row.className = (row.rowIndex % 2)? 'odd':'even'; + addCell(row, row.rowIndex); + addCell(row, p); + addCell(row, e[p]); + } + + document.body.appendChild(table); +} + +window.onload = function(event){ + showEventProperties(event); +} +</script> +</head> + +<body> +<h1>Properties of the DOM <span id="eventType"></span> Event Object</h1> +</body> + +</html> +</pre> + +<h2 id="Example_8:_Using_the_DOM_Table_Interface" name="Example_8:_Using_the_DOM_Table_Interface">範例八：使用 DOM Table 介面</h2> + +<p>DOM HTMLTableElement 介面提供了一些方便的方法用於創建和操作資料表。兩種常用的方法是{{domxref("HTMLTableElement.insertRow")}}和{{domxref("tableRow.insertCell")}}.。</p> + +<p>增加一行和一些細格到現有的資料表：</p> + +<pre class="brush:html"><table id="table0"> + <tr> + <td>Row 0 Cell 0</td> + <td>Row 0 Cell 1</td> + </tr> +</table> + +<script> +var table = document.getElementById('table0'); +var row = table.insertRow(-1); +var cell, + text; + +for (var i = 0; i < 2; i++) { + cell = row.insertCell(-1); + text = 'Row ' + row.rowIndex + ' Cell ' + i; + cell.appendChild(document.createTextNode(text)); +} +</script> +</pre> + +<h3 id="Notes" name="Notes">提醒</h3> + +<ul> + <li>表格的{{domxref("element.innerHTML","innerHTML")}}屬性絕不應該被用來修改表，雖然你可以用它來寫一個完整的表格或細格中的內容。</li> + <li>如果用 DOM 核心方法<font face="Consolas, Liberation Mono, Courier, monospace"> </font>{{domxref("document.createElement")}} 和<font face="Consolas, Liberation Mono, Courier, monospace"> </font>{{domxref("Node.appendChild")}} 來建立表格的行和細格，IE 會要求它們附加到一個 tbody 元素，而其它瀏覽器允許它們附加到一個 table 元素（行會被添加到最後的 tbody 元素）。</li> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLTableElement#Methods">表格介面</a>還有一些可用於創建和修改的表格的便利方法。</li> +</ul> + +<h2 id="Subnav">Subnav</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/Document_Object_Model">DOM Reference</a></li> + <li><a href="/en-US/docs/Web/API/Document_Object_Model/Introduction">Introduction to the DOM</a></li> + <li><a href="/en-US/docs/Web/API/Document_Object_Model/Events">Events and the DOM</a></li> + <li><a href="/en-US/docs/Web/API/Document_Object_Model/Examples">Examples</a></li> +</ul> diff --git a/files/zh-tw/web/api/document_object_model/how_to_create_a_dom_tree/index.html b/files/zh-tw/web/api/document_object_model/how_to_create_a_dom_tree/index.html new file mode 100644 index 0000000000..02a3ac01e2 --- /dev/null +++ b/files/zh-tw/web/api/document_object_model/how_to_create_a_dom_tree/index.html @@ -0,0 +1,145 @@ +--- +title: 如何建立 DOM 樹 +slug: Web/API/Document_Object_Model/How_to_create_a_DOM_tree +translation_of: Web/API/Document_object_model/How_to_create_a_DOM_tree +--- +<p>{{draft}}</p> + +<p>This page describes how to use the <a class="external" href="http://www.w3.org/TR/DOM-Level-3-Core/core.html">DOM Core</a> API in JavaScript to create and modify DOM objects. It applies to all Gecko-based applications (such as Firefox) both in privileged (extensions) and unprivileged (web pages) code.</p> + +<h3 id="Dynamically_creating_a_DOM_tree" name="Dynamically_creating_a_DOM_tree">Dynamically creating a DOM tree</h3> + +<p>Consider the following XML document:</p> + +<pre class="brush: xml"><?xml version="1.0"?> +<people> + <person first-name="eric" middle-initial="H" last-name="jung"> + <address street="321 south st" city="denver" state="co" country="usa"/> + <address street="123 main st" city="arlington" state="ma" country="usa"/> + </person> + + <person first-name="jed" last-name="brown"> + <address street="321 north st" city="atlanta" state="ga" country="usa"/> + <address street="123 west st" city="seattle" state="wa" country="usa"/> + <address street="321 south avenue" city="denver" state="co" country="usa"/> + </person> +</people> +</pre> + +<p>The W3C DOM API, supported by Mozilla, can be used to create an in-memory representation of this document like so:</p> + +<pre class="brush: js">var doc = document.implementation.createDocument("", "", null); +var peopleElem = doc.createElement("people"); + +var personElem1 = doc.createElement("person"); +personElem1.setAttribute("first-name", "eric"); +personElem1.setAttribute("middle-initial", "h"); +personElem1.setAttribute("last-name", "jung"); + +var addressElem1 = doc.createElement("address"); +addressElem1.setAttribute("street", "321 south st"); +addressElem1.setAttribute("city", "denver"); +addressElem1.setAttribute("state", "co"); +addressElem1.setAttribute("country", "usa"); +personElem1.appendChild(addressElem1); + +var addressElem2 = doc.createElement("address"); +addressElem2.setAttribute("street", "123 main st"); +addressElem2.setAttribute("city", "arlington"); +addressElem2.setAttribute("state", "ma"); +addressElem2.setAttribute("country", "usa"); +personElem1.appendChild(addressElem2); + +var personElem2 = doc.createElement("person"); +personElem2.setAttribute("first-name", "jed"); +personElem2.setAttribute("last-name", "brown"); + +var addressElem3 = doc.createElement("address"); +addressElem3.setAttribute("street", "321 north st"); +addressElem3.setAttribute("city", "atlanta"); +addressElem3.setAttribute("state", "ga"); +addressElem3.setAttribute("country", "usa"); +personElem2.appendChild(addressElem3); + +var addressElem4 = doc.createElement("address"); +addressElem4.setAttribute("street", "123 west st"); +addressElem4.setAttribute("city", "seattle"); +addressElem4.setAttribute("state", "wa"); +addressElem4.setAttribute("country", "usa"); +personElem2.appendChild(addressElem4); + +var addressElem5 = doc.createElement("address"); +addressElem5.setAttribute("street", "321 south avenue"); +addressElem5.setAttribute("city", "denver"); +addressElem5.setAttribute("state", "co"); +addressElem5.setAttribute("country", "usa"); +personElem2.appendChild(addressElem5); + +peopleElem.appendChild(personElem1); +peopleElem.appendChild(personElem2); +doc.appendChild(peopleElem); +</pre> + +<p>See also the <a href="/en/XUL_Tutorial/Document_Object_Model" title="en/XUL_Tutorial/Document_Object_Model"> DOM chapter of the XUL Tutorial</a>.</p> + +<p>You can automate the creation of a DOM tree using a <a href="/en/JXON#JXON_reverse_algorithms" title="en/JXON#JXON_reverse_algorithms">JXON reverse algorithm</a> in association with the following JSON representation:</p> + +<pre class="brush: js">{ + "people": { + "person": [{ + "address": [{ + "@street": "321 south st", + "@city": "denver", + "@state": "co", + "@country": "usa" + }, { + "@street": "123 main st", + "@city": "arlington", + "@state": "ma", + "@country": "usa" + }], + "@first-name": "eric", + "@middle-initial": "H", + "@last-name": "jung" + }, { + "address": [{ + "@street": "321 north st", + "@city": "atlanta", + "@state": "ga", + "@country": "usa" + }, { + "@street": "123 west st", + "@city": "seattle", + "@state": "wa", + "@country": "usa" + }, { + "@street": "321 south avenue", + "@city": "denver", + "@state": "co", + "@country": "usa" + }], + "@first-name": "jed", + "@last-name": "brown" + }] + } +} +</pre> + +<h3 id="So_what.3F" name="So_what.3F">So what?</h3> + +<p>DOM trees can be <a href="/en/Using_XPath" title="en/Using_XPath"> queried using XPath expressions</a>, converted to strings or written to a local or remote files using <a href="/en/Parsing_and_serializing_XML" title="en/Parsing_and_serializing_XML"> XMLSerializer</a> (without having to first convert to a string), <a href="/en/DOM/XMLHttpRequest" title="en/XMLHttpRequest">POSTed to a web server</a> (via <code>XMLHttpRequest</code>), transformed using <a href="/en/XSLT" title="en/XSLT">XSLT</a>, <a href="/en/XLink" title="en/XLink">XLink</a>, converted to a JavaScript object through a <a href="/en/JXON" title="en/JXON">JXON algorithm</a>, etc.</p> + +<p>You can use DOM trees to model data which isn't well-suited for RDF (or perhaps you just don't like RDF). Another application is that, since XUL is XML, the UI of your application can be dynamically manipulated, downloaded, uploaded, saved, loaded, converted, or transformed quite easily.</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a class="internal" href="/en/XML" title="en/XML">XML</a></li> + <li><a class="internal" href="/en/JXON" title="en/JXON">JXON</a></li> + <li><a class="internal" href="/en/XPath" title="en/XPath">XPath</a></li> + <li><a class="internal" href="/en/E4X" title="en/E4X">E4X (ECMAScript for XML)</a></li> + <li><a class="internal" href="/en/Parsing_and_serializing_XML" title="en/Parsing_and_serializing_XML">Parsing and serializing XML</a></li> + <li><a class="internal" href="/en/DOM/XMLHttpRequest" title="en/XMLHttpRequest">XMLHttpRequest</a></li> +</ul> + +<p>{{ languages( { "fr": "fr/Comment_cr\u00e9er_un_arbre_DOM", "ja": "ja/How_to_create_a_DOM_tree", "zh-cn": "zh-cn/How_to_create_a_DOM_tree" } ) }}</p> diff --git a/files/zh-tw/web/api/document_object_model/index.html b/files/zh-tw/web/api/document_object_model/index.html new file mode 100644 index 0000000000..a2e07c7fdd --- /dev/null +++ b/files/zh-tw/web/api/document_object_model/index.html @@ -0,0 +1,384 @@ +--- +title: 文件物件模型 (DOM) +slug: Web/API/Document_Object_Model +tags: + - DOM + - DOM Reference + - DOM 參考 + - Intermediate +translation_of: Web/API/Document_Object_Model +--- +<p>{{DefaultAPISidebar("DOM")}}</p> + +<p><strong>文件物件模型（<em>Document Object Model, DOM</em>）</strong>是 HTML、XML 和 SVG 文件的程式介面。它提供了一個文件（樹）的結構化表示法，並定義讓程式可以存取並改變文件架構、風格和內容的方法。DOM 提供了文件以擁有屬性與函式的節點與物件組成的結構化表示。節點也可以附加事件處理程序，一旦觸發事件就會執行處理程序。 本質上，它將網頁與腳本或程式語言連結在一起。</p> + +<p>雖然常常使用 JavaScript 來存取 DOM，但它本身並不是 JavaScript 語言的一部分，而且它也可以被其他語言存取（雖然不太常見就是了）。</p> + +<p>這裡有一篇 DOM 的<a href="/zh-TW/docs/DOM/DOM_Reference/Introduction">介紹</a>可供查閱。</p> + +<h2 id="DOM_介面">DOM 介面</h2> + +<div class="index"> +<ul> + <li>{{domxref("Attr")}}</li> + <li>{{domxref("CharacterData")}}</li> + <li>{{domxref("ChildNode")}} {{experimental_inline}}</li> + <li>{{domxref("Comment")}}</li> + <li>{{domxref("CustomEvent")}}</li> + <li>{{domxref("Document")}}</li> + <li>{{domxref("DocumentFragment")}}</li> + <li>{{domxref("DocumentType")}}</li> + <li>{{domxref("DOMError")}}</li> + <li>{{domxref("DOMException")}}</li> + <li>{{domxref("DOMImplementation")}}</li> + <li>{{domxref("DOMString")}}</li> + <li>{{domxref("DOMTimeStamp")}}</li> + <li>{{domxref("DOMSettableTokenList")}}</li> + <li>{{domxref("DOMStringList")}}</li> + <li>{{domxref("DOMTokenList")}}</li> + <li>{{domxref("Element")}}</li> + <li>{{domxref("Event")}}</li> + <li>{{domxref("EventTarget")}}</li> + <li>{{domxref("HTMLCollection")}}</li> + <li>{{domxref("MutationObserver")}}</li> + <li>{{domxref("MutationRecord")}}</li> + <li>{{domxref("Node")}}</li> + <li>{{domxref("NodeFilter")}}</li> + <li>{{domxref("NodeIterator")}}</li> + <li>{{domxref("NodeList")}}</li> + <li>{{domxref("ParentNode")}} {{experimental_inline}}</li> + <li>{{domxref("ProcessingInstruction")}}</li> + <li>{{domxref("Range")}}</li> + <li>{{domxref("Text")}}</li> + <li>{{domxref("TreeWalker")}}</li> + <li>{{domxref("URL")}}</li> + <li>{{domxref("Window")}}</li> + <li>{{domxref("Worker")}}</li> + <li>{{domxref("XMLDocument")}} {{experimental_inline}}</li> +</ul> +</div> + +<h2 id="棄用的_DOM_介面">棄用的 DOM 介面</h2> + +<p>文件物件模型正被大量的簡化。為了達成這個目的，下這些介面是在 DOM level 3 或更早的規範中就被刪掉了。由於不清楚是否會被再度納入，請姑且當他們已經被遺棄，並避免使用：</p> + +<div class="index"> +<ul> + <li>{{domxref("CDATASection")}}</li> + <li>{{domxref("DOMConfiguration")}}</li> + <li>{{domxref("DOMErrorHandler")}}</li> + <li>{{domxref("DOMImplementationList")}}</li> + <li>{{domxref("DOMImplementationRegistry")}}</li> + <li>{{domxref("DOMImplementationSource")}}</li> + <li>{{domxref("DOMLocator")}}</li> + <li>{{domxref("DOMObject")}}</li> + <li>{{domxref("DOMUserData")}}</li> + <li>{{domxref("Entity")}}</li> + <li>{{domxref("EntityReference")}}</li> + <li>{{domxref("NamedNodeMap")}}</li> + <li>{{domxref("NameList")}}</li> + <li>{{domxref("Notation")}}</li> + <li>{{domxref("TypeInfo")}}</li> + <li>{{domxref("UserDataHandler")}}</li> + <li> </li> +</ul> +</div> + +<h2 id="HTML_介面">HTML 介面</h2> + +<p>一份包含 html 的文件會透過 {{domxref("HTMLDocument")}} 介面來描述。注意 HTML 規範也擴展了 {{domxref("Document")}} 介面。</p> + +<p><code>HTMLDocument</code> 物件也提供了瀏覽器功能的存取：分頁、透過 {{domxref("Window")}} 介面描繪頁面的視窗、與其相關的 {{domxref("window.style", "樣式")}} （通常是 CSS ）、與本文關聯的瀏覽器 {{domxref("window.history", "歷史")}}、以及一個文件內的 {{domxref("Selection", "選擇器")}}。</p> + +<h3 id="HTML_元素介面">HTML 元素介面</h3> + +<div class="index"> +<ul> + <li>{{domxref("HTMLAnchorElement")}}</li> + <li>{{domxref("HTMLAppletElement")}}</li> + <li>{{domxref("HTMLAreaElement")}}</li> + <li>{{domxref("HTMLAudioElement")}}</li> + <li>{{domxref("HTMLBaseElement")}}</li> + <li>{{domxref("HTMLBodyElement")}}</li> + <li>{{domxref("HTMLBRElement")}}</li> + <li>{{domxref("HTMLButtonElement")}}</li> + <li>{{domxref("HTMLCanvasElement")}}</li> + <li>{{domxref("HTMLDataElement")}}</li> + <li>{{domxref("HTMLDataListElement")}}</li> + <li>{{domxref("HTMLDialogElement")}}</li> + <li>{{domxref("HTMLDirectoryElement")}}</li> + <li>{{domxref("HTMLDivElement")}}</li> + <li>{{domxref("HTMLDListElement")}}</li> + <li>{{domxref("HTMLElement")}}</li> + <li>{{domxref("HTMLEmbedElement")}}</li> + <li>{{domxref("HTMLFieldSetElement")}}</li> + <li>{{domxref("HTMLFontElement")}}</li> + <li>{{domxref("HTMLFormElement")}}</li> + <li>{{domxref("HTMLFrameElement")}}</li> + <li>{{domxref("HTMLFrameSetElement")}}</li> + <li>{{domxref("HTMLHeadElement")}}</li> + <li>{{domxref("HTMLHeadingElement")}}</li> + <li>{{domxref("HTMLHtmlElement")}}</li> + <li>{{domxref("HTMLHRElement")}}</li> + <li>{{domxref("HTMLIFrameElement")}}</li> + <li>{{domxref("HTMLImageElement")}}</li> + <li>{{domxref("HTMLInputElement")}}</li> + <li>{{domxref("HTMLKeygenElement")}}</li> + <li>{{domxref("HTMLLabelElement")}}</li> + <li>{{domxref("HTMLLegendElement")}}</li> + <li>{{domxref("HTMLLIElement")}}</li> + <li>{{domxref("HTMLLinkElement")}}</li> + <li>{{domxref("HTMLMapElement")}}</li> + <li>{{domxref("HTMLMediaElement")}}</li> + <li>{{domxref("HTMLMenuElement")}}</li> + <li>{{domxref("HTMLMetaElement")}}</li> + <li>{{domxref("HTMLMeterElement")}}</li> + <li>{{domxref("HTMLModElement")}}</li> + <li>{{domxref("HTMLObjectElement")}}</li> + <li>{{domxref("HTMLOListElement")}}</li> + <li>{{domxref("HTMLOptGroupElement")}}</li> + <li>{{domxref("HTMLOptionElement")}}</li> + <li>{{domxref("HTMLOutputElement")}}</li> + <li>{{domxref("HTMLParagraphElement")}}</li> + <li>{{domxref("HTMLParamElement")}}</li> + <li>{{domxref("HTMLPreElement")}}</li> + <li>{{domxref("HTMLProgressElement")}}</li> + <li>{{domxref("HTMLQuoteElement")}}</li> + <li>{{domxref("HTMLScriptElement")}}</li> + <li>{{domxref("HTMLSelectElement")}}</li> + <li>{{domxref("HTMLSourceElement")}}</li> + <li>{{domxref("HTMLSpanElement")}}</li> + <li>{{domxref("HTMLStyleElement")}}</li> + <li>{{domxref("HTMLTableElement")}}</li> + <li>{{domxref("HTMLTableCaptionElement")}}</li> + <li>{{domxref("HTMLTableCellElement")}}</li> + <li>{{domxref("HTMLTableDataCellElement")}}</li> + <li>{{domxref("HTMLTableHeaderCellElement")}}</li> + <li>{{domxref("HTMLTableColElement")}}</li> + <li>{{domxref("HTMLTableRowElement")}}</li> + <li>{{domxref("HTMLTableSectionElement")}}</li> + <li>{{domxref("HTMLTextAreaElement")}}</li> + <li>{{domxref("HTMLTimeElement")}}</li> + <li>{{domxref("HTMLTitleElement")}}</li> + <li>{{domxref("HTMLTrackElement")}}</li> + <li>{{domxref("HTMLUListElement")}}</li> + <li>{{domxref("HTMLUnknownElement")}}</li> + <li>{{domxref("HTMLVideoElement")}}</li> +</ul> +</div> + +<h3 id="其他介面">其他介面</h3> + +<div class="index"> +<ul> + <li>{{domxref("CanvasRenderingContext2D")}}</li> + <li>{{domxref("CanvasGradient")}}</li> + <li>{{domxref("CanvasPattern")}}</li> + <li>{{domxref("TextMetrics")}}</li> + <li>{{domxref("ImageData")}}</li> + <li>{{domxref("CanvasPixelArray")}}</li> + <li>{{domxref("NotifyAudioAvailableEvent")}}</li> + <li>{{domxref("HTMLAllCollection")}}</li> + <li>{{domxref("HTMLFormControlsCollection")}}</li> + <li>{{domxref("HTMLOptionsCollection")}}</li> + <li>{{domxref("HTMLPropertiesCollection")}}</li> + <li>{{domxref("DOMStringMap")}}</li> + <li>{{domxref("RadioNodeList")}}</li> + <li>{{domxref("MediaError")}}</li> +</ul> +</div> + +<h3 id="棄用的_HTML_介面">棄用的 HTML 介面</h3> + +<div class="index"> +<ul> + <li>{{domxref("HTMLBaseFontElement")}}</li> + <li>{{domxref("HTMLIsIndexElement")}}</li> +</ul> +</div> + +<h2 id="SVG_介面">SVG 介面</h2> + +<h3 id="SVG_元素介面">SVG 元素介面</h3> + +<div class="index"> +<ul> + <li>{{domxref("SVGAElement")}}</li> + <li>{{domxref("SVGAltGlyphElement")}}</li> + <li>{{domxref("SVGAltGlyphDefElement")}}</li> + <li>{{domxref("SVGAltGlyphItemElement")}}</li> + <li>{{domxref("SVGAnimationElement")}}</li> + <li>{{domxref("SVGAnimateElement")}}</li> + <li>{{domxref("SVGAnimateColorElement")}}</li> + <li>{{domxref("SVGAnimateMotionElement")}}</li> + <li>{{domxref("SVGAnimateTransformElement")}}</li> + <li>{{domxref("SVGCircleElement")}}</li> + <li>{{domxref("SVGClipPathElement")}}</li> + <li>{{domxref("SVGColorProfileElement")}}</li> + <li>{{domxref("SVGComponentTransferFunctionElement")}}</li> + <li>{{domxref("SVGCursorElement")}}</li> + <li>{{domxref("SVGDefsElement")}}</li> + <li>{{domxref("SVGDescElement")}}</li> + <li>{{domxref("SVGElement")}}</li> + <li>{{domxref("SVGEllipseElement")}}</li> + <li>{{domxref("SVGFEBlendElement")}}</li> + <li>{{domxref("SVGFEColorMatrixElement")}}</li> + <li>{{domxref("SVGFEComponentTransferElement")}}</li> + <li>{{domxref("SVGFECompositeElement")}}</li> + <li>{{domxref("SVGFEConvolveMatrixElement")}}</li> + <li>{{domxref("SVGFEDiffuseLightingElement")}}</li> + <li>{{domxref("SVGFEDisplacementMapElement")}}</li> + <li>{{domxref("SVGFEDistantLightElement")}}</li> + <li>{{domxref("SVGFEFloodElement")}}</li> + <li>{{domxref("SVGFEGaussianBlurElement")}}</li> + <li>{{domxref("SVGFEImageElement")}}</li> + <li>{{domxref("SVGFEMergeElement")}}</li> + <li>{{domxref("SVGFEMergeNodeElement")}}</li> + <li>{{domxref("SVGFEMorphologyElement")}}</li> + <li>{{domxref("SVGFEOffsetElement")}}</li> + <li>{{domxref("SVGFEPointLightElement")}}</li> + <li>{{domxref("SVGFESpecularLightingElement")}}</li> + <li>{{domxref("SVGFESpotLightElement")}}</li> + <li>{{domxref("SVGFETileElement")}}</li> + <li>{{domxref("SVGFETurbulenceElement")}}</li> + <li>{{domxref("SVGFEFuncRElement")}}</li> + <li>{{domxref("SVGFEFuncGElement")}}</li> + <li>{{domxref("SVGFEFuncBElement")}}</li> + <li>{{domxref("SVGFEFuncAElement")}}</li> + <li>{{domxref("SVGFilterElement")}}</li> + <li>{{domxref("SVGFilterPrimitiveStandardAttributes")}}</li> + <li>{{domxref("SVGFontElement")}}</li> + <li>{{domxref("SVGFontFaceElement")}}</li> + <li>{{domxref("SVGFontFaceFormatElement")}}</li> + <li>{{domxref("SVGFontFaceNameElement")}}</li> + <li>{{domxref("SVGFontFaceSrcElement")}}</li> + <li>{{domxref("SVGFontFaceUriElement")}}</li> + <li>{{domxref("SVGForeignObjectElement")}}</li> + <li>{{domxref("SVGGElement")}}</li> + <li>{{domxref("SVGGlyphElement")}}</li> + <li>{{domxref("SVGGlyphRefElement")}}</li> + <li>{{domxref("SVGGradientElement")}}</li> + <li>{{domxref("SVGHKernElement")}}</li> + <li>{{domxref("SVGImageElement")}}</li> + <li>{{domxref("SVGLinearGradientElement")}}</li> + <li>{{domxref("SVGLineElement")}}</li> + <li>{{domxref("SVGMarkerElement")}}</li> + <li>{{domxref("SVGMaskElement")}}</li> + <li>{{domxref("SVGMetadataElement")}}</li> + <li>{{domxref("SVGMissingGlyphElement")}}</li> + <li>{{domxref("SVGMPathElement")}}</li> + <li>{{domxref("SVGPathElement")}}</li> + <li>{{domxref("SVGPatternElement")}}</li> + <li>{{domxref("SVGPolylineElement")}}</li> + <li>{{domxref("SVGPolygonElement")}}</li> + <li>{{domxref("SVGRadialGradientElement")}}</li> + <li>{{domxref("SVGRectElement")}}</li> + <li>{{domxref("SVGScriptElement")}}</li> + <li>{{domxref("SVGSetElement")}}</li> + <li>{{domxref("SVGStopElement")}}</li> + <li>{{domxref("SVGStyleElement")}}</li> + <li>{{domxref("SVGSVGElement")}}</li> + <li>{{domxref("SVGSwitchElement")}}</li> + <li>{{domxref("SVGSymbolElement")}}</li> + <li>{{domxref("SVGTextElement")}}</li> + <li>{{domxref("SVGTextPathElement")}}</li> + <li>{{domxref("SVGTitleElement")}}</li> + <li>{{domxref("SVGTRefElement")}}</li> + <li>{{domxref("SVGTSpanElement")}}</li> + <li>{{domxref("SVGUseElement")}}</li> + <li>{{domxref("SVGViewElement")}}</li> + <li>{{domxref("SVGVKernElement")}}</li> +</ul> +</div> + +<h3 id="SVG_資料型別介面">SVG 資料型別介面</h3> + +<p>這裡是資料型態的 DOM API，在 SVG 特性和性質的定義中被使用。</p> + +<div class="note"> +<p><strong><strong>備註：</strong></strong>從 {{Gecko("5.0")}}<strong> </strong>開始，下列 SVG 相關的 DOM 介面物件的表示清單，現在可以被索引且可以像陣列般被取用；此外，他們也有 length 屬性來標示其清單中的項目個數：{{domxref("SVGLengthList")}}、{{domxref("SVGNumberList")}}、{{domxref("SVGPathSegList")}}，和 {{domxref("SVGPointList")}}。</p> +</div> + +<h4 id="靜態類型">靜態類型</h4> + +<div class="index"> +<ul> + <li>{{domxref("SVGAngle")}}</li> + <li>{{domxref("SVGColor")}}</li> + <li>{{domxref("SVGICCColor")}}</li> + <li>{{domxref("SVGElementInstance")}}</li> + <li>{{domxref("SVGElementInstanceList")}}</li> + <li>{{domxref("SVGLength")}}</li> + <li>{{domxref("SVGLengthList")}}</li> + <li>{{domxref("SVGMatrix")}}</li> + <li>{{domxref("SVGNumber")}}</li> + <li>{{domxref("SVGNumberList")}}</li> + <li>{{domxref("SVGPaint")}}</li> + <li>{{domxref("SVGPoint")}}</li> + <li>{{domxref("SVGPointList")}}</li> + <li>{{domxref("SVGPreserveAspectRatio")}}</li> + <li>{{domxref("SVGRect")}}</li> + <li>{{domxref("SVGStringList")}}</li> + <li>{{domxref("SVGTransform")}}</li> + <li>{{domxref("SVGTransformList")}}</li> +</ul> +</div> + +<h4 id="動畫類型">動畫類型</h4> + +<div class="index"> +<ul> + <li>{{domxref("SVGAnimatedAngle")}}</li> + <li>{{domxref("SVGAnimatedBoolean")}}</li> + <li>{{domxref("SVGAnimatedEnumeration")}}</li> + <li>{{domxref("SVGAnimatedInteger")}}</li> + <li>{{domxref("SVGAnimatedLength")}}</li> + <li>{{domxref("SVGAnimatedLengthList")}}</li> + <li>{{domxref("SVGAnimatedNumber")}}</li> + <li>{{domxref("SVGAnimatedNumberList")}}</li> + <li>{{domxref("SVGAnimatedPreserveAspectRatio")}}</li> + <li>{{domxref("SVGAnimatedRect")}}</li> + <li>{{domxref("SVGAnimatedString")}}</li> + <li>{{domxref("SVGAnimatedTransformList")}}</li> +</ul> +</div> + +<h3 id="SMIL_相關介面">SMIL 相關介面</h3> + +<div class="index"> +<ul> + <li>{{domxref("ElementTimeControl")}}</li> + <li>{{domxref("TimeEvent")}}</li> +</ul> +</div> + +<h3 id="其他的_SVG_介面">其他的 SVG 介面</h3> + +<div class="index"> +<ul> + <li>{{domxref("SVGAnimatedPathData")}}</li> + <li>{{domxref("SVGAnimatedPoints")}}</li> + <li>{{domxref("SVGColorProfileRule")}}</li> + <li>{{domxref("SVGCSSRule")}}</li> + <li>{{domxref("SVGExternalResourcesRequired")}}</li> + <li>{{domxref("SVGFitToViewBox")}}</li> + <li>{{domxref("SVGLangSpace")}}</li> + <li>{{domxref("SVGLocatable")}}</li> + <li>{{domxref("SVGRenderingIntent")}}</li> + <li>{{domxref("SVGStylable")}}</li> + <li>{{domxref("SVGTests")}}</li> + <li>{{domxref("SVGTextContentElement")}}</li> + <li>{{domxref("SVGTextPositioningElement")}}</li> + <li>{{domxref("SVGTransformable")}}</li> + <li>{{domxref("SVGUnitTypes")}}</li> + <li>{{domxref("SVGURIReference")}}</li> + <li>{{domxref("SVGViewSpec")}}</li> + <li>{{domxref("SVGZoomAndPan")}}</li> +</ul> +</div> + +<h2 id="See_also" name="See_also">相關連結</h2> + +<ul> + <li><a href="/zh-TW/docs/DOM/DOM_Reference/Examples">DOM 範例</a></li> +</ul> diff --git a/files/zh-tw/web/api/document_object_model/whitespace/index.html b/files/zh-tw/web/api/document_object_model/whitespace/index.html new file mode 100644 index 0000000000..7e584a3dd6 --- /dev/null +++ b/files/zh-tw/web/api/document_object_model/whitespace/index.html @@ -0,0 +1,183 @@ +--- +title: DOM 中的空白字元 +slug: Web/API/Document_Object_Model/Whitespace +tags: + - DOM + - 所有類別 +translation_of: Web/API/Document_Object_Model/Whitespace +--- +<h4 id=".E5.95.8F.E9.A1.8C.E8.AA.AA.E6.98.8E" name=".E5.95.8F.E9.A1.8C.E8.AA.AA.E6.98.8E">問題說明</h4> +<p><a href="zh_tw/DOM">DOM</a> 裡的空白字元會讓處理節點結構時增加不少麻煩。Mozilla 相關軟體中，原始文件裡所有空白字元都會在 DOM 中出現（不包括標籤內含的空白字元）。這樣的處理方式有其必要，一方面編輯器中可逕行排列文字、二方面 <a href="zh_tw/CSS">CSS</a> 裡的 <code>white-space: pre</code> 也才能發揮作用。 如此一來就表示：</p> +<ul> + <li>有些空白字元會自成一個文字節點。</li> + <li>有些空白字元會與其他字串合成一個文字節點。</li> +</ul> +<p>換句話說，下面這段程式碼的 DOM 節點結構就如附圖一般，其中「\n」代表換行字元：</p> +<pre class="eval"><!-- My document --> +<html> +<head> + <title>My Document</title> +</head> +<body> + <h1>Header</h1> + <p> + Paragraph + </p> +</body> +</html> +</pre> + +<p><img height="306" src="https://mdn.mozillademos.org/files/854/whitespace_tree.png" width="618"></p> + +<p>這麼一來，要使用 DOM 遊走於節點結構間又不想要無用的空白字元時，會有點困難。</p> +<h4 id=".E5.8A.A9.E4.BD.A0.E4.B8.80.E8.87.82.E4.B9.8B.E5.8A.9B" name=".E5.8A.A9.E4.BD.A0.E4.B8.80.E8.87.82.E4.B9.8B.E5.8A.9B">助你一臂之力</h4> +<p>以下的 JavaScript 程式碼定義了許多函式，讓你處理 DOM 中的空白字元時能輕鬆點：</p> +<pre>/** + * 以下所謂的「空白字元」代表： + * "\t" TAB \u0009 （移位字元） + * "\n" LF \u000A （換行字元） + * "\r" CR \u000D （歸位字元） + * " " SPC \u0020 （真正的空白） + * + * 不包括 JavaScript 的「\s」，因為那代表如不斷行字元等其他字元。 + */ + + +/** + * 測知某節點的文字內容是否全為空白。 + * + * @參數 nod |CharacterData| 類的節點（如 |Text|、|Comment| 或 |CDATASection|）。 + * @傳回值 若 |nod| 的文字內容全為空白則傳回 true，否則傳回 false。 + */ +function is_all_ws( nod ) +{ + // Use ECMA-262 Edition 3 String and RegExp features + return !(/[^\t\n\r ]/.test(nod.data)); +} + + +/** + * 測知是否該略過某節點。 + * + * @參數 nod DOM1 |Node| 物件 + * @傳回值 若 |Text| 節點內僅有空白字元或為 |Comment| 節點時，傳回 true， + * 否則傳回 false。 + */ + +function is_ignorable( nod ) +{ + return ( nod.nodeType == 8) || // 註解節點 + ( (nod.nodeType == 3) && is_all_ws(nod) ); // 僅含空白字元的文字節點 +} + +/** + * 此為會跳過空白字元節點及註解節點的 |previousSibling| 函式 + * （ |previousSibling| 是 DOM 節點的特性值，為該節點的前一個節點。） + * + * @參數 sib 節點。 + * @傳回值 有兩種可能： + * 1) |sib| 的前一個「非空白、非註解」節點（由 |is_ignorable| 測知。） + * 2) 若該節點前無任何此類節點，則傳回 null。 + */ +function node_before( sib ) +{ + while ((sib = sib.previousSibling)) { + if (!is_ignorable(sib)) return sib; + } + return null; +} + +/** + * 此為會跳過空白字元節點及註解節點的 |nextSibling| 函式 + * + * @參數 sib 節點。 + * @傳回值 有兩種可能： + * 1) |sib| 的下一個「非空白、非註解」節點。 + * 2) 若該節點後無任何此類節點，則傳回 null。 + */ +function node_after( sib ) +{ + while ((sib = sib.nextSibling)) { + if (!is_ignorable(sib)) return sib; + } + return null; +} + +/** + * 此為會跳過空白字元節點及註解節點的 |lastChild| 函式 + * （ lastChild| 是 DOM 節點的特性值，為該節點之中最後一個子節點。） + * + * @參數 par 節點。 + * @傳回值 有兩種可能： + * 1) |par| 中最後一個「非空白、非註解」節點。 + * 2) 若該節點中無任何此類子節點，則傳回 null。 + */ +function last_child( par ) +{ + var res=par.lastChild; + while (res) { + if (!is_ignorable(res)) return res; + res = res.previousSibling; + } + return null; +} + +/** + * 此為會跳過空白字元節點及註解節點的 |firstChild| 函式 + * + * @參數 par 節點。 + * @傳回值 有兩種可能： + * 1) |par| 中第一個「非空白、非註解」節點。 + * 2) 若該節點中無任何此類子節點，則傳回 null。 + */ +function first_child( par ) +{ + var res=par.firstChild; + while (res) { + if (!is_ignorable(res)) return res; + res = res.nextSibling; + } + return null; +} + +/** + * 此為傳回值不包含文字節點資料的首尾所有空白字元、 + * 並將兩個以上的空白字元縮減為一個的 |data| 函式。 + *（ data 是 DOM 文字節點的特性值，為該文字節點中的資料。） + * + * @參數 txt 欲傳回其中資料的文字節點 + * @傳回值 文字節點的內容，其中空白字元已依前述方式處理。 + */ +function data_of( txt ) +{ + var data = txt.data; + // Use ECMA-262 Edition 3 String and RegExp features + data = data.replace(/[\t\n\r ]+/g, " "); + if (data.charAt(0) == " ") + data = data.substring(1, data.length); + if (data.charAt(data.length - 1) == " ") + data = data.substring(0, data.length - 1); + return data; +} +</pre> +<h4 id=".E7.AF.84.E4.BE.8B" name=".E7.AF.84.E4.BE.8B">範例</h4> +<p>以下示範上述函式的應用方法，在節點結構中依序檢查、找出內容為「<code>"This is the third paragraph"</code>」的節點，並修改其 class 屬性及文字內容。</p> +<pre>var cur = first_child(document.getElementById("test")); +while (cur) +{ + if (data_of(cur.firstChild) == "This is the third paragraph.") + { + cur.className = "magic"; + cur.firstChild.data = "This is the magic paragraph."; + } + cur = node_after(cur); +} +</pre> +<div class="originaldocinfo"> + <h4 id=".E5.8E.9F.E6.96.87.E8.B3.87.E8.A8.8A" name=".E5.8E.9F.E6.96.87.E8.B3.87.E8.A8.8A">原文資訊</h4> + <ul> + <li>作者：<a class="external" href="http://dbaron.org">L. David Baron</a></li> + <li>最後更新：January 1, 2003</li> + <li>版權資訊：© 1998-2005 by individual mozilla.org contributors; 內容部份以 <a class="external" href="http://www.mozilla.org/foundation/licensing/website-content.html">創意公用</a>方式授權。</li> + </ul> +</div> diff --git a/files/zh-tw/web/api/document_object_model/事件/index.html b/files/zh-tw/web/api/document_object_model/事件/index.html new file mode 100644 index 0000000000..ff4ecfe572 --- /dev/null +++ b/files/zh-tw/web/api/document_object_model/事件/index.html @@ -0,0 +1,69 @@ +--- +title: 事件與DOM +slug: Web/API/Document_Object_Model/事件 +translation_of: Web/API/Document_Object_Model/Events +--- +<h2 id="Introduction" name="Introduction">Introduction</h2> + +<p>This chapter describes the DOM Event Model. The <a href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-Event">Event</a> interface itself is described, as well as the interfaces for event registration on nodes in the DOM, and <a href="/en-US/docs/Web/API/EventTarget.addEventListener">event listeners</a>, and several longer examples that show how the various event interfaces relate to one another.</p> + +<p>There is an excellent diagram that clearly explains the three phases of event flow through the DOM in the <a href="http://www.w3.org/TR/DOM-Level-3-Events/#dom-event-architecture">DOM Level 3 Events draft</a>.</p> + +<p>Also see <a href="/en-US/docs/DOM/DOM_Reference/Examples#Example_5:_Event_Propagation">Example 5: Event Propagation</a> in the Examples chapter for a more detailed example of how events move through the DOM.</p> + +<h2 id="DOM_event_handler_List" name="DOM_event_handler_List">Registering event listeners</h2> + +<p>There are 3 ways to register event handlers for a DOM element.</p> + +<h3 id="EventTarget.addEventListener" name="EventTarget.addEventListener"><a href="/en-US/docs/Web/API/EventTarget.addEventListener"><code>EventTarget.addEventListener</code></a></h3> + +<pre class="brush: js">// Assuming myButton is a button element +myButton.addEventListener('click', function(){alert('Hello world');}, false); +</pre> + +<p>This is the method you should use in modern web pages.</p> + +<p>Note: Internet Explorer 6-8 didn't support this method, offering a similar {{domxref("EventTarget.attachEvent")}} API instead. For cross-browser compatibility use one of the many JavaScript libraries available.</p> + +<p>More details can be found on the {{domxref("EventTarget.addEventListener")}} reference page.</p> + +<h3 id="HTML_attribute" name="HTML_attribute"><a href="/en-US/docs/Web/Guide/HTML/Event_attributes">HTML attribute</a></h3> + +<pre class="brush: html"><button onclick="alert('Hello world!')"> +</pre> + +<p>The JavaScript code in the attribute is passed the Event object via the <code>event</code> parameter. <a href="http://dev.w3.org/html5/spec/webappapis.html#the-event-handler-processing-algorithm">The return value is treated in a special way, described in the HTML specification</a>.</p> + +<p>This way should be avoided. This makes the markup bigger and less readable. Concerns of content/structure and behavior are not well-separated, making a bug harder to find.</p> + +<h3 id="DOM_element_properties" name="DOM_element_properties">DOM element properties</h3> + +<pre class="brush: js">// Assuming myButton is a button element +myButton.onclick = function(event){alert('Hello world');}; +</pre> + +<p>The function can be defined to take an <code>event</code> parameter. <a href="http://dev.w3.org/html5/spec/webappapis.html#the-event-handler-processing-algorithm">The return value is treated in a special way, described in the HTML specification</a>.</p> + +<p>The problem with this method is that only one handler can be set per element and per event.</p> + +<h2 id="Accessing_Event_interfaces">Accessing Event interfaces</h2> + +<p>Event handlers may be attached to various objects including DOM elements, document, the <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects">window object</a>, etc. When an event occurs, an event object is created and passed sequentially to the event listeners.</p> + +<p>The {{domxref("Event")}} interface is accessible from within the handler function, via the event object passed as the first argument. The following simple example shows how an event object is passed to the event handler function, and can be used from within one such function.</p> + +<pre class="brush: js">function foo(evt) { + // the evt parameter is automatically assigned the event object + alert(evt); +} +table_el.onclick = foo; +</pre> + +<h2 id="Subnav">Subnav</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/Document_Object_Model">DOM Reference</a></li> + <li><a href="/en-US/docs/Web/API/Document_Object_Model/Introduction">Introduction to the DOM</a></li> + <li><a href="/en-US/docs/Web/API/Document_Object_Model/Events">Events and the DOM</a></li> + <li><a href="/en-US/docs/Web/API/Document_Object_Model/Examples">Examples</a></li> +</ul> diff --git a/files/zh-tw/web/api/documentfragment/index.html b/files/zh-tw/web/api/documentfragment/index.html new file mode 100644 index 0000000000..a3926841e0 --- /dev/null +++ b/files/zh-tw/web/api/documentfragment/index.html @@ -0,0 +1,248 @@ +--- +title: DocumentFragment +slug: Web/API/DocumentFragment +translation_of: Web/API/DocumentFragment +--- +<p>{{ ApiRef("DOM") }}</p> + +<p><strong><span class="external"><code>DocumentFragment</code></span></strong> 介面表示了一個沒有父節點的最小化文件物件。<code>DocumentFragment</code> 被當作一種輕量化的 {{domxref("Document")}}，用如同標準文件一般的方式保存片段的文件結構（由節點組成）。關鍵的區別在於文件片段不是真實的 DOM 結構，文件片段的變動並不會影響目前的網頁文件，也不會導致回流（{{Glossary("reflow")}}）或引起任何影響效能的情況發生。</p> + +<p>一般的用法是建立一個 <code>DocumentFragment</code> 物件，在此物件中組織一個 DOM 的子樹。再使用 {{domxref("Node")}} 介面定義的方法，如 {{domxref("Node.appendChild", "appendChild()")}} 或 {{domxref("Node.insertBefore", "insertBefore()")}} 將這個文件片段加入或插入目前頁面的 DOM 當中。執行這個將文件片段中的節點置入 DOM 的動作之後，會留下一個空的 <code>DocumentFragment</code> 物件（只會插入物件中的節點，<code>DocumentFragment</code> 物件本身不會被插入）。由於文件片段中的所有節點是一次性的被插入目前頁面文件當中，故回流及頁面渲染只會被觸發一次，所以可用插入 <code>DocumentFragment</code> 物件的方式取代傳統分別插入多個節點至 DOM（將節點一個一個分次進行插入）的操作方式。</p> + +<p>此介面也適合與 Web components 搭配使用：{{HTMLElement("template")}} 元素在其 {{domxref("HTMLTemplateElement.content")}} 屬性中便包含了一個 <code>DocumentFragment</code> 物件。</p> + +<p>可使用 {{domxref("document.createDocumentFragment()")}} 方法或 <code>DocumentFragment</code> 的建構式來建立一個空的 <code>DocumentFragment</code> 物件。</p> + +<h2 id="Specification" name="Specification">屬性</h2> + +<p><em>This interface has no specific properties, but inherits those of its parent, </em><em>{{domxref("Node")}}, and implements those of the {{domxref("ParentNode")}} interface.</em></p> + +<dl> + <dt>{{ domxref("ParentNode.children") }} {{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns a live {{domxref("HTMLCollection")}} containing all objects of type {{domxref("Element")}} that are children of the <code>DocumentFragment</code> object.</dd> + <dt>{{ domxref("ParentNode.firstElementChild") }} {{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns the {{domxref("Element")}} that is the first child of the <code>DocumentFragment</code> object, or <code>null</code> if there is none.</dd> + <dt>{{ domxref("ParentNode.lastElementChild") }} {{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns the {{domxref("Element")}} that is the last child of the <code>DocumentFragment</code> object, or <code>null</code> if there is none.</dd> + <dt>{{ domxref("ParentNode.childElementCount") }} {{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns an <code>unsigned long</code> giving the amount of children that the <code>DocumentFragment</code> has.</dd> +</dl> + +<h2 id="建構式">建構式</h2> + +<dl> + <dt>{{ domxref("DocumentFragment.DocumentFragment()", "DocumentFragment()") }} {{experimental_inline}}</dt> + <dd>Returns an empty <code>DocumentFragment</code> object.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>This interface inherits the methods of its parent, {{domxref("Node")}}<em>, and implements those of the {{domxref("ParentNode")}} interface</em></em><em>.</em></p> + +<dl> + <dt>{{domxref("DocumentFragment.find()")}} {{experimental_inline}}</dt> + <dd>Returns the first matching {{domxref("Element")}} in the tree of the <code>DocumentFragment</code>.</dd> + <dt>{{domxref("DocumentFragment.findAll()")}} {{experimental_inline}}</dt> + <dd>Returns a {{domxref("NodeList")}} of matching {{domxref("Element")}} in the tree of the <code>DocumentFragment</code>.</dd> + <dt>{{domxref("DocumentFragment.querySelector()")}}</dt> + <dd>Returns the first {{domxref("Element")}} node within the <code>DocumentFragment</code>, in document order, that matches the specified selectors.</dd> + <dt>{{domxref("DocumentFragment.querySelectorAll()")}}</dt> + <dd>Returns a {{domxref("NodeList")}} of all the {{domxref("Element")}} nodes within the <code>DocumentFragment</code> that match the specified selectors.</dd> +</dl> + +<dl> + <dt>{{domxref("DocumentFragment.getElementById()")}}</dt> + <dd>Returns the first {{domxref("Element")}} node within the <code style="font-size: 14px;">DocumentFragment</code>, in document order, that matches the specified ID.</dd> +</dl> + +<h2 id="Specifications" name="Specifications">規範</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('DOM WHATWG', '#interface-documentfragment', 'DocumentFragment')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>Added the constructor and the implementation of {{domxref("ParentNode")}}.</td> + </tr> + <tr> + <td>{{SpecName('Selectors API Level 2', '#the-apis', 'DocumentFragment')}}</td> + <td>{{Spec2('Selectors API Level 2')}}</td> + <td>Added the <code>find()</code> and <code>findAll()</code> methods.</td> + </tr> + <tr> + <td>{{SpecName('Selectors API Level 1', '#the-apis', 'DocumentFragment')}}</td> + <td>{{Spec2('Selectors API Level 1')}}</td> + <td>Added the <code>querySelector()</code> and <code>querySelectorAll()</code> methods.</td> + </tr> + <tr> + <td>{{SpecName('DOM3 Core', 'core.html#ID-B63ED1A3', 'DocumentFragment')}}</td> + <td>{{Spec2('DOM3 Core')}}</td> + <td>No change from {{SpecName('DOM2 Core')}}</td> + </tr> + <tr> + <td>{{SpecName('DOM2 Core', 'core.html#ID-B63ED1A3', 'DocumentFragment')}}</td> + <td>{{Spec2('DOM2 Core')}}</td> + <td>No change from {{SpecName('DOM1')}}</td> + </tr> + <tr> + <td>{{SpecName('DOM1', 'level-one-core.html#ID-B63ED1A3', 'DocumentFragment')}}</td> + <td>{{Spec2('DOM1')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>1.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>querySelector()</code> and <code>querySelectorAll()</code></td> + <td>1.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>8.0</td> + <td>10.0</td> + <td>3.2 (525.3)</td> + </tr> + <tr> + <td><code>findAll()</code> and <code>find() </code>{{experimental_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>DocumentFragment()</code> constructor {{experimental_inline}}</td> + <td>28.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("24.0")}}</td> + <td>{{CompatNo}}</td> + <td>15.0</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>ParentNode</code> properties {{experimental_inline}}</td> + <td>28.0</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop("25.0")}}</td> + <td>{{CompatNo}}</td> + <td>15.0</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>ParentNode</code> methods {{experimental_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</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>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("1.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>querySelector()</code> and <code>querySelectorAll()</code></td> + <td>2.1</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("1.0")}}</td> + <td>8.0</td> + <td>10.0</td> + <td>3.2 (525.3)</td> + </tr> + <tr> + <td><code>findAll()</code> and <code>find() </code>{{experimental_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>DocumentFragment()</code> constructor {{experimental_inline}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("24.0")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>ParentNode</code> properties {{experimental_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile("25.0")}}</td> + <td>{{CompatNo}}</td> + <td>5.0</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>ParentNode</code> methods {{experimental_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/docs/DOM/DOM_Reference" title="/en-US/docs/DOM/DOM_Reference">The DOM interfaces index.</a></li> +</ul> diff --git a/files/zh-tw/web/api/documenttype/index.html b/files/zh-tw/web/api/documenttype/index.html new file mode 100644 index 0000000000..f0d7ae32b4 --- /dev/null +++ b/files/zh-tw/web/api/documenttype/index.html @@ -0,0 +1,200 @@ +--- +title: DocumentType +slug: Web/API/DocumentType +tags: + - API + - DOM + - DocumentType + - Interface +translation_of: Web/API/DocumentType +--- +<div>{{APIRef("DOM")}}</div> + +<p><strong><code>DocumentType</code></strong> 介面表示了一個代表文件類型的 {{domxref("Node")}} 節點。</p> + +<p>{{InheritanceDiagram}}</p> + +<h2 id="屬性">屬性</h2> + +<p><em>此介面繼承了其父介面 {{domxref("Node")}} 的屬性，以及實作了 {{domxref("ChildNode")}} 介面。</em></p> + +<dl> + <dt>{{domxref("DocumentType.entities")}} {{readonlyInline}} {{obsolete_Inline}}</dt> + <dd>A {{domxref("NamedNodeMap")}} of entities declared in the DTD. Every node in this map implements the {{domxref("Entity")}} interface.</dd> + <dt>{{domxref("DocumentType.internalSubset")}} {{readonlyInline}} {{obsolete_Inline}}</dt> + <dd>A {{domxref("DOMString")}} of the internal subset, or <code>null</code> if there is none. Eg <code>"<!ELEMENT foo (bar)>"</code>.</dd> + <dt>{{domxref("DocumentType.name")}} {{readonlyInline}}</dt> + <dd>A {{domxref("DOMString")}}, eg <code>"html"</code> for <code><!DOCTYPE HTML></code>.</dd> + <dt>{{domxref("DocumentType.notations")}} {{readonlyInline}} {{obsolete_Inline}}</dt> + <dd>A {{domxref("NamedNodeMap")}} with notations declared in the DTD. Every node in this map implements the {{domxref("Notation")}} interface.</dd> + <dt>{{domxref("DocumentType.publicId")}} {{readonlyInline}}</dt> + <dd>A {{domxref("DOMString")}}, eg <code>"-//W3C//DTD HTML 4.01//EN"</code>, empty string for HTML5.</dd> + <dt>{{domxref("DocumentType.systemId")}} {{readonlyInline}}</dt> + <dd>A {{domxref("DOMString")}}, eg <code>"http://www.w3.org/TR/html4/strict.dtd"</code>, empty string for HTML5.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>此介面繼承了其父介面 {{domxref("Node")}} 的方法，以及實作了 {{domxref("ChildNode")}} 介面。</em></p> + +<dl> + <dt>{{domxref("ChildNode.remove()")}} {{experimental_inline}}</dt> + <dd>Removes the object from its parent children list.</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('DOM WHATWG', '#documenttype', 'DocumentType')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>Added implemention of the {{domxref("ChildNode")}} interface.<br> + Removed the <code>internalSubset</code>, <code>entities</code>, and <code>notation</code> properties.</td> + </tr> + <tr> + <td>{{SpecName('DOM3 Core', 'core.html#ID-412266927', 'DocumentType')}}</td> + <td>{{Spec2('DOM3 Core')}}</td> + <td>No change from {{SpecName('DOM2 Core')}}.</td> + </tr> + <tr> + <td>{{SpecName('DOM2 Core', 'core.html#ID-412266927', 'DocumentType')}}</td> + <td>{{Spec2('DOM2 Core')}}</td> + <td>Added the <code>publicID</code>, <code>systemID</code>, and <code>internalSubset</code> properties.</td> + </tr> + <tr> + <td>{{SpecName('DOM1', 'level-one-core.html#ID-412266927', 'DocumentType')}}</td> + <td>{{Spec2('DOM1')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>1.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>entities</code> and <code>notations</code></td> + <td>1.0<sup>[1]</sup></td> + <td>{{CompatVersionUnknown}}<sup>[3]</sup></td> + <td>{{CompatGeckoDesktop("1.0")}}<br> + {{CompatNo}}{{CompatGeckoDesktop("6.0")}}</td> + <td>{{CompatVersionUnknown}}<sup>[3]</sup></td> + <td>{{CompatVersionUnknown}}<sup>[1]</sup></td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>internalSubset</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}} (not anymore in any case)</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>Implements {{domxref("ChildNode")}}</td> + <td>29.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("25.0")}}<sup>[2]</sup></td> + <td>{{CompatNo}}</td> + <td>16.0</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>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("1.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>entities</code> and <code>notations</code></td> + <td>{{CompatVersionUnknown}}<sup>[1]</sup></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("1.0")}}<br> + {{CompatNo}}{{CompatGeckoMobile("6.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>internalSubset</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>Implements {{domxref("ChildNode")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("25.0")}}<sup>[2]</sup></td> + <td>{{CompatNo}}</td> + <td>16.0</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] The Chromium project plans to drop supports for the <code>internalSubset</code>, <code>entities</code> and <code>notations</code> methods.</p> + +<p>[2] Firefox 25 also added the <code>previousElementSibling</code> and <code>nextElementSibling properties</code>, this was removed in Firefox 28 due to compatibility problems.</p> + +<p>[3] <code>entities</code> and <code>notations</code> properties exist in IE and Edge, but seem to always be <code>null</code>?</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/zh-TW/docs/DOM/DOM_Reference">The DOM interfaces index.</a></li> + <li>{{domxref("Entity")}}</li> + <li>{{domxref("Notation")}}</li> +</ul> diff --git a/files/zh-tw/web/api/domparser/index.html b/files/zh-tw/web/api/domparser/index.html new file mode 100644 index 0000000000..4ded67f1c3 --- /dev/null +++ b/files/zh-tw/web/api/domparser/index.html @@ -0,0 +1,200 @@ +--- +title: DOMParser +slug: Web/API/DOMParser +tags: + - DOMParser SVG XML +translation_of: Web/API/DOMParser +--- +<p>{{APIRef("DOM")}}{{SeeCompatTable}}</p> + +<p><code>DOMParser可以將XML或是HTML格式的字串轉成</code>DOM <a href="/en-US/docs/DOM/document">文件</a>. <code>DOMParser</code>的規格請參閱<a href="http://html5.org/specs/dom-parsing.html">DOM解譯與串流化</a>.</p> + +<p>請注意<a href="/en-US/docs/DOM/XMLHttpRequest" title="DOM/XMLHttpRequest">XMLHttpRequest</a>解譯的是URL連結內容裡的XML與HTML文件.</p> + +<h2 id="產生一個_DOMParser">產生一個 DOMParser</h2> + +<p>" <code>new DOMParser()" 可產生DOMParser</code>.</p> + +<p><code>關於如何在Firefox外掛程式中產生DOMParser,</code>請參考<code><a href="/en-US/docs/nsIDOMParser" title="nsIDOMParser">nsIDOMParser</a>文件</code></p> + +<h2 id="解譯_XML">解譯 XML</h2> + +<p>產生解譯物件後，請呼叫<code>parseFromString方法函式來將XML字串轉換成DOM物件</code>:</p> + +<pre class="brush: js">var parser = new DOMParser(); +var doc = parser.parseFromString(stringContainingXMLSource, "application/xml"); +</pre> + +<h3 id="Error_handling" name="Error_handling">錯誤處理</h3> + +<p>請注意如果解譯過程出錯,目前的<code>DOMParser不會丟出異常物件(exception)，但是會回傳一個錯誤文件</code>(請看程式臭蟲{{Bug(45566)}}):</p> + +<pre class="brush:xml"><parsererror xmlns="http://www.mozilla.org/newlayout/xml/parsererror.xml"> +(error description) +<sourcetext>(a snippet of the source XML)</sourcetext> +</parsererror> +</pre> + +<p>解譯錯誤也會記錄在錯誤終端機中（<a href="/en-US/docs/Error_Console" title="Error Console">Error Console</a>）, 紀錄裡頭的文件URI (如下) 則為錯誤來源.</p> + +<h2 id="解譯_SVG_或_HTML_文件">解譯 SVG 或 HTML 文件</h2> + +<p><code>DOMParser也可以用來解譯 </code>SVG 文件 {{geckoRelease("10.0")}} 或是 HTML 文件 {{geckoRelease("12.0")}}. 可以依 MIME 格式，輸出三種不同格式. 如果MIME 格式是 <code>text/xml</code>,輸出的格式為 <code>XMLDocument</code>, 如果 MIME 格式是 <code>image/svg+xml</code>, 輸出格式為 <code>SVGDocument,</code> 如果 MIME 格式是 <code>text/html</code>, 輸出格式則為 <code>HTMLDocument</code>.</p> + +<pre class="brush: js">var parser = new DOMParser(); +var doc = parser.parseFromString(stringContainingXMLSource, "application/xml"); +// returns a Document, but not a SVGDocument nor a HTMLDocument + +parser = new DOMParser(); +doc = parser.parseFromString(stringContainingXMLSource, "image/svg+xml"); +// returns a SVGDocument, which also is a Document. + +parser = new DOMParser(); +doc = parser.parseFromString(stringContainingHTMLSource, "text/html"); +// returns a HTMLDocument, which also is a Document. +</pre> + +<h3 id="其他瀏覽器可用的DOMParser_HTML_外掛程式">其他瀏覽器可用的DOMParser HTML 外掛程式</h3> + +<pre class="brush: js">/* + * DOMParser HTML extension + * 2012-09-04 + * + * By Eli Grey, http://eligrey.com + * Public domain. + * NO WARRANTY EXPRESSED OR IMPLIED. USE AT YOUR OWN RISK. + */ + +/*! @source https://gist.github.com/1129031 */ +/*global document, DOMParser*/ + +(function(DOMParser) { + "use strict"; + + var + proto = DOMParser.prototype + , nativeParse = <span style="font-size: 1rem;">proto</span><span style="font-size: 1rem;">.parseFromString</span> + ; + + // Firefox/Opera/IE throw errors on unsupported types + try { + // WebKit returns null on unsupported types + if ((new DOMParser()).parseFromString("", "text/html")) { + // text/html parsing is natively supported + return; + } + } catch (ex) {} + + <span style="font-size: 1rem;">proto</span><span style="font-size: 1rem;">.parseFromString = function(markup, type) {</span> + if (/^\s*text\/html\s*(?:;|$)/i.test(type)) { + var + doc = document.implementation.createHTMLDocument("") + ; + if (markup.toLowerCase().indexOf('<!doctype') > -1) { + doc.documentElement.innerHTML = markup; + } + else { + doc.body.innerHTML = markup; + } + return doc; + } else { + return <span style="font-size: 1rem;">nativeParse</span><span style="font-size: 1rem;">.apply(this, arguments);</span> + } + }; +}(DOMParser)); +</pre> + +<h3 id="DOMParser_from_ChromeJSMXPCOMPrivileged_Scope">DOMParser from Chrome/JSM/XPCOM/Privileged Scope</h3> + +<p>See article here: <a href="/en-US/docs/nsIDOMParser">nsIDOMParser</a></p> + +<h2 id="Browser_compatibility" name="Browser_compatibility">瀏覽器相容性</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 (WebKit)</th> + </tr> + <tr> + <td>XML support</td> + <td>{{CompatChrome(1)}}</td> + <td>{{CompatGeckoDesktop(1)}}</td> + <td>{{CompatIE(9)}}</td> + <td>{{CompatOpera(8)}}</td> + <td>{{CompatSafari(3.2)}}</td> + </tr> + <tr> + <td>SVG support</td> + <td>{{CompatChrome(4)}}</td> + <td>{{CompatGeckoDesktop(10.0)}}</td> + <td>{{CompatIE(10)}}</td> + <td>{{CompatOpera(15)}}</td> + <td>{{CompatSafari(3.2)}}</td> + </tr> + <tr> + <td>HTML support</td> + <td>{{CompatChrome(30)}}</td> + <td>{{CompatGeckoDesktop(12.0)}}</td> + <td>{{CompatIE(10)}}</td> + <td>{{CompatOpera(17)}}</td> + <td>{{CompatSafari(7.1)}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>XML support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>SVG support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile(10.0)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>HTML support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile(12.0)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="See_also" name="See_also">參考資料</h2> + +<ul> + <li><a href="/en-US/docs/Parsing_and_serializing_XML" title="Parsing_and_serializing_XML">Parsing and serializing XML</a></li> + <li><a href="/en-US/docs/DOM/XMLHttpRequest" title="DOM/XMLHttpRequest">XMLHttpRequest</a></li> + <li><a href="/en-US/docs/XMLSerializer" title="XMLSerializer">XMLSerializer</a></li> + <li><a href="/en-US/Add-ons/Code_snippets/HTML_to_DOM">Parsing HTML to DOM</a></li> +</ul> diff --git a/files/zh-tw/web/api/domstring/index.html b/files/zh-tw/web/api/domstring/index.html new file mode 100644 index 0000000000..396773ce7f --- /dev/null +++ b/files/zh-tw/web/api/domstring/index.html @@ -0,0 +1,50 @@ +--- +title: DOMString +slug: Web/API/DOMString +translation_of: Web/API/DOMString +--- +<p>{{APIRef("DOM")}}</p> + +<p><strong><code>DOMString</code></strong> 是編碼為 UTF-16 的字串。當 JavaScript 使用這類字串時， <code>DOMString</code> 會映射成一個 {{jsxref("String")}}.</p> + +<p>傳送 <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/null">null</a></code> 給接受 <code>DOMString</code> 的 method 或參數時，會將其轉換成 <code>"null"</code>。</p> + +<h2 id="Specification" name="Specification">Specifications</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('WebIDL', '#idl-DOMString', 'DOMString')}}</td> + <td>{{Spec2('WebIDL')}}</td> + <td>修正定義文件用詞。並移除奇特的極端請況。</td> + </tr> + <tr> + <td>{{SpecName('DOM3 Core', 'core.html#DOMString', 'DOMString')}}</td> + <td>{{Spec2('DOM3 Core')}}</td> + <td>No change from {{SpecName('DOM2 Core')}}</td> + </tr> + <tr> + <td>{{SpecName('DOM2 Core', 'core.html#ID-C74D1578', 'DOMString')}}</td> + <td>{{Spec2('DOM2 Core')}}</td> + <td>No change from {{SpecName('DOM1')}}</td> + </tr> + <tr> + <td>{{SpecName('DOM1', 'level-one-core.html#ID-C74D1578', 'DOMString')}}</td> + <td>{{Spec2('DOM1')}}</td> + <td>初次定義 DOMString 。</td> + </tr> + </tbody> +</table> + +<h2 id="延伸閱讀">延伸閱讀</h2> + +<ul> + <li><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/String" title="/en-US/docs/Web/API/DOMString">String</a></li> + <li><a href="/en-US/docs/Web/JavaScript/Typed_arrays/String_view" title="/en-US/docs/Web/JavaScript/Typed_arrays/String_view"><code>StringView</code> – a C-like representation of strings based on typed arrays</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/DOMString/Binary">Binary strings</a></li> +</ul> diff --git a/files/zh-tw/web/api/domtokenlist/index.html b/files/zh-tw/web/api/domtokenlist/index.html new file mode 100644 index 0000000000..998c3b6e48 --- /dev/null +++ b/files/zh-tw/web/api/domtokenlist/index.html @@ -0,0 +1,117 @@ +--- +title: DOMTokenList +slug: Web/API/DOMTokenList +translation_of: Web/API/DOMTokenList +--- +<p>{{APIRef("DOM")}}{{gecko_minversion_header("1.9.2")}}</p> + +<p><code><strong>DOMTokenList</strong></code> 介面表示了一個以空格作為分隔的內容集，通常來自 {{domxref("Element.classList")}}、{{domxref("HTMLLinkElement.relList")}}、{{domxref("HTMLAnchorElement.relList")}} 或 {{domxref("HTMLAreaElement.relList")}} 等屬性。本介面與 {{jsxref("Array")}} 同樣是由 <code>0</code> 開始索引，且 <code>DOMTokenList</code> 是區分大小寫的。</p> + +<h2 id="屬性">屬性</h2> + +<p><em>This interface doesn't inherit any property.</em></p> + +<dl> + <dt>{{domxref("DOMTokenList.length")}} {{ReadOnlyInline}}</dt> + <dd>Is an <code>integer</code> representing the number of objects stored in the object.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>This interface doesn't inherit any method.</em></p> + +<dl> + <dt>{{domxref("DOMTokenList.item()")}}</dt> + <dd>Returns an item in the list by its index (or undefined if the number is greater than or equal to the length of the list, prior to {{gecko("7.0")}} returned null)</dd> + <dt>{{domxref("DOMTokenList.contains()")}}</dt> + <dd>Returns <code>true</code> if the underlying string contains <em>token</em>, otherwise <code>false</code></dd> + <dt>{{domxref("DOMTokenList.add()")}}</dt> + <dd>Adds <em>token</em> to the underlying string</dd> + <dt>{{domxref("DOMTokenList.remove()")}}</dt> + <dd>Removes <em>token</em> from the underlying string</dd> + <dt>{{domxref("DOMTokenList.replace()")}}</dt> + <dd>Replaces an existing <em>token</em> with a new token.</dd> + <dt>{{domxref("DOMTokenList.supports()")}}</dt> + <dd>Returns <code>true</code> if a given <em>token</em> is in the associated attribute's supported tokens.</dd> + <dt>{{domxref("DOMTokenList.toggle()")}}</dt> + <dd>Removes <em>token</em> from string and returns false. If <em>token</em> doesn't exist it's added and the function returns true</dd> +</dl> + +<h2 id="規範">規範</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("DOM WHATWG", "#interface-domtokenlist", "DOMTokenList")}}</td> + <td>{{Spec2("DOM WHATWG")}}</td> + <td>Initial definition</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>10</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</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>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + <th>Chrome for Android</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("DOMSettableTokenList")}} (object that extends DOMTokenList with settable <em>.value</em> property)</li> +</ul> diff --git a/files/zh-tw/web/api/dragevent/datatransfer/index.html b/files/zh-tw/web/api/dragevent/datatransfer/index.html new file mode 100644 index 0000000000..f46de41856 --- /dev/null +++ b/files/zh-tw/web/api/dragevent/datatransfer/index.html @@ -0,0 +1,118 @@ +--- +title: DragEvent.dataTransfer +slug: Web/API/DragEvent/dataTransfer +translation_of: Web/API/DragEvent/dataTransfer +--- +<div>{{APIRef("HTML Drag and Drop API")}}</div> + +<p><code><strong>DataEvent.dataTransfer</strong></code> 屬性保留了拖曳操作中的資料（指向一個 {{domxref("DataTransfer")}} 物件）。</p> + +<p>此屬性為 {{readonlyInline}}。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">var <var>data</var> = <var>dragEvent</var>.dataTransfer; +</pre> + +<h3 id="回傳值">回傳值</h3> + +<dl> + <dt><code>data</code></dt> + <dd>一個保存 {{domxref("DragEvent")}} 當中資料的 {{domxref("DataTransfer")}} 物件。</dd> +</dl> + +<h2 id="範例">範例</h2> + +<p>This example illustrates accessing the drag and drop data within the {{event("dragend")}} event handler.</p> + +<pre class="brush: js">function process_data(d) { + // Process the data ... +} + +dragTarget.addEventListener("dragend", function(ev) { + // Call the drag and drop data processor + if (ev.dataTransfer != null) process_data(ev.dataTransfer); + }, false); +</pre> + +<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("HTML WHATWG", "interaction.html#dom-dragevent-datatransfer", "DragEvent.dataTransfer")}}</td> + <td>{{Spec2("HTML WHATWG")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("HTML5.1", "editing.html#dom-dragevent-datatransfer", "DragEvent.dataTransfer")}}</td> + <td>{{Spec2("HTML5.1")}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>4</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>10</td> + <td>12</td> + <td>3.1</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>Chrome for Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatIE("10")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> diff --git a/files/zh-tw/web/api/dragevent/index.html b/files/zh-tw/web/api/dragevent/index.html new file mode 100644 index 0000000000..45f233ab58 --- /dev/null +++ b/files/zh-tw/web/api/dragevent/index.html @@ -0,0 +1,160 @@ +--- +title: DragEvent +slug: Web/API/DragEvent +translation_of: Web/API/DragEvent +--- +<div>{{APIRef("HTML Drag and Drop API")}}</div> + +<p><strong><code>DragEvent</code></strong> 介面是一種 {{domxref("Event","DOM event")}}，定義了拖放操作時產生的事件物件。使用者藉由把指標裝置 (例如滑鼠) 放到有效區域並拖移到另一個新的位置 ( 如另外一個 DOM 元素 ) 來開始一個拖動的動作。 而應用程式可以自由地決定互動的方式來達到符合該應用程式的使用情境。</p> + + + +<p class="note">This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref("Event")}}.</p> + +<h2 id="屬性">屬性</h2> + +<dl> + <dt>{{domxref('DragEvent.dataTransfer')}} {{readonlyInline}}</dt> + <dd>The data that is transferred during a drag and drop interaction.</dd> +</dl> + +<h2 id="建構式">建構式</h2> + +<p class="note">Although this interface has a constructor, it is not possible to create a useful DataTransfer object from script, since {{domxref("DataTransfer")}} objects have a processing and security model that is coordinated by the browser during drag-and-drops.</p> + +<dl> + <dt>{{domxref("DragEvent.DragEvent", "DragEvent()")}}</dt> + <dd>Creates a synthetic and untrusted DragEvent.</dd> +</dl> + +<h2 id="事件類型">事件類型</h2> + +<dl> + <dt>{{event('drag')}}</dt> + <dd>在『被選擇的物件』被拖曳時觸發。</dd> + <dt>{{event('dragend')}}</dt> + <dd>在『被選擇的物件』結束拖曳時觸發 (就是放開滑鼠鍵、或按下 Esc 鍵時)。</dd> + <dt>{{event('dragenter')}}</dt> + <dd>當『被選擇的物件』被拖曳到『可以當目標的物件』時, 在『進入』該目標物件上方的瞬間觸發。注意, 不是『被選擇的物件』觸發此事件, 而是『可以當目標的物件』。</dd> + <dt>{{event('dragexit')}}</dt> + <dd>This event is fired when an element is no longer the drag operation's immediate selection target.</dd> + <dt>{{event('dragleave')}}</dt> + <dd>當『被選擇的物件』被拖曳到『可以當目標的物件』時, 在『離開』該目標物件上方的瞬間觸發。注意, 不是『被選擇的物件』觸發此事件, 而是『可以當目標的物件』。</dd> + <dt>{{event('dragover')}}</dt> + <dd>當『被選擇的物件』被拖曳到『可以當目標的物件』的上方時觸發 (頻率大約每秒數次)。注意, 不是『被選擇的物件』觸發此事件, 而是『可以當目標的物件』 。</dd> + <dt>{{event('dragstart')}}</dt> + <dd>在『被選擇的物件』開始拖曳時觸發。</dd> + <dt>{{event('drop')}}</dt> + <dd>當『被選擇的物件』被拖曳、放到『目標物件』時觸發。注意, 不是『被選擇的物件』觸發此事件, 而是『目標物件』。</dd> +</dl> + +<h2 id="通用事件處理器">通用事件處理器</h2> + +<dl> + <dt>{{domxref('GlobalEventHandlers.ondrag')}}</dt> + <dd>A {{domxref('GlobalEventHandlers','global event handler')}} for the {{event('drag')}} event.</dd> + <dt>{{domxref('GlobalEventHandlers.ondragend')}}</dt> + <dd>A {{domxref('GlobalEventHandlers','global event handler')}} for the {{event('dragend')}} event.</dd> + <dt>{{domxref('GlobalEventHandlers.ondragenter')}}</dt> + <dd>A {{domxref('GlobalEventHandlers','global event handler')}} for the {{event('dragenter')}} event.</dd> + <dt>{{domxref('GlobalEventHandlers.ondragexit')}}</dt> + <dd>A {{domxref('GlobalEventHandlers','global event handler')}} for the {{event('dragexit')}} event.</dd> + <dt>{{domxref('GlobalEventHandlers.ondragleave')}}</dt> + <dd>A {{domxref('GlobalEventHandlers','global event handler')}} for the {{event('dragleave')}} event.</dd> + <dt>{{domxref('GlobalEventHandlers.ondragover')}}</dt> + <dd>A {{domxref('GlobalEventHandlers','global event handler')}} for the {{event('dragover')}} event.</dd> + <dt>{{domxref('GlobalEventHandlers.ondragstart')}}</dt> + <dd>A {{domxref('GlobalEventHandlers','global event handler')}} for the {{event('dragstart')}} event.</dd> + <dt>{{domxref('GlobalEventHandlers.ondrop')}}</dt> + <dd>A {{domxref('GlobalEventHandlers','global event handler')}} for the {{event('drop')}} event.</dd> +</dl> + +<h2 id="範例">範例</h2> + +<p>An Example of each property, constructor, event type and global event handlers is included in their respective reference page.</p> + +<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("HTML WHATWG", "interaction.html#the-dragevent-interface", "DragEvent")}}</td> + <td>{{Spec2("HTML WHATWG")}}</td> + <td></td> + </tr> + <tr> + <td>{{SpecName("HTML5.1", "editing.html#the-dragevent-interface", "DragEvent")}}</td> + <td>{{Spec2("HTML5.1")}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>4</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>10</td> + <td>12</td> + <td>3.1</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>Chrome for Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatIE("10")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="參見">參見</h2> + +<p>{{page("/zh-TW/docs/Web/API/DataTransfer", "參見")}}</p> diff --git a/files/zh-tw/web/api/element/attributes/index.html b/files/zh-tw/web/api/element/attributes/index.html new file mode 100644 index 0000000000..ce24985c8b --- /dev/null +++ b/files/zh-tw/web/api/element/attributes/index.html @@ -0,0 +1,121 @@ +--- +title: Element.attributes +slug: Web/API/Element/attributes +translation_of: Web/API/Element/attributes +--- +<p>{{ APIRef("DOM") }}</p> + +<p> </p> + +<p>The <strong><code>Element.attributes</code></strong> property returns a live collection of all attribute nodes registered to the specified node. It is a {{domxref("NamedNodeMap")}}, not an <code>Array</code>, so it has no {{jsxref("Array")}} methods and the {{domxref("Attr")}} nodes' indexes may differ among browsers. To be more specific, <code>attributes</code> is a key/value pair of strings that represents any information regarding that attribute.</p> + +<p> </p> + +<p>Element.attribute 特性會把特定節點裡所有的屬性變成一個集合,然後回傳出來. 這是一個 <a href="https://developer.mozilla.org/en-US/docs/Web/API/NamedNodeMap">NamedNodeMap</a>, 而並非一個陣列. 所以它並沒有陣列的方法和在瀏覽器中 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Attr">Attr</a>節點裡的索引值也可能不同. 更詳細的來說, attributes 是一個鍵/值的配對, 它包含了所有有關於這個節點屬性的資訊</p> + +<p> </p> + +<p>Syntax</p> + +<pre class="syntaxbox">var <em>attr</em> =<em> element</em>.attributes; +</pre> + +<h2 id="Example" name="Example">Example</h2> + +<h3 id="Basic_examples">Basic examples</h3> + +<pre class="brush: js">// Get the first <p> element in the document +var para = document.getElementsByTagName("p")[0]; +var atts = para.attributes;</pre> + +<h3 id="Enumerating_elements_attributes" name="Enumerating_elements_attributes">Enumerating elements attributes</h3> + +<p>Numerical indexing is useful for going through all of an element's attributes.<br> + The following example runs through the attribute nodes for the element in the document with id "paragraph", and prints each attribute's value.</p> + +<pre class="brush: html"><!DOCTYPE html> + +<html> + + <head> + <title>Attributes example</title> + <script type="text/javascript"> + function listAttributes() { + var paragraph = document.getElementById("paragraph"); + var result = document.getElementById("result"); + + // First, let's verify that the paragraph has some attributes + if (paragraph.hasAttributes()) { + var attrs = paragraph.attributes; + var output = ""; + for(var i = attrs.length - 1; i >= 0; i--) { + output += attrs[i].name + "->" + attrs[i].value; + } + result.value = output; + } else { + result.value = "No attributes to show"; + } + } + </script> + </head> + +<body> + <p id="paragraph" style="color: green;">Sample Paragraph</p> + <form action=""> + <p> + <input type="button" value="Show first attribute name and value" + onclick="listAttributes();"> + <input id="result" type="text" value=""> + </p> + </form> +</body> +</html></pre> + +<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('DOM WHATWG', '#dom-element-attributes', 'Element.attributes')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>From {{SpecName('DOM3 Core')}}, moved from {{domxref("Node")}} to {{domxref("Element")}}</td> + </tr> + <tr> + <td>{{SpecName('DOM3 Core', 'core.html#ID-84CF096', 'Element.attributes')}}</td> + <td>{{Spec2('DOM3 Core')}}</td> + <td>No change from {{SpecName('DOM2 Core')}}</td> + </tr> + <tr> + <td>{{SpecName('DOM2 Core', 'core.html#ID-84CF096', 'Element.attributes')}}</td> + <td>{{Spec2('DOM2 Core')}}</td> + <td>No change from {{SpecName('DOM1')}}</td> + </tr> + <tr> + <td>{{SpecName('DOM1', 'level-one-core.html#ID-84CF096', 'Element.attributes')}}</td> + <td>{{Spec2('DOM1')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<div class="hidden"> +<p>The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> +</div> + +<p>{{Compat("api.Element.attributes")}}</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li>{{domxref("NamedNodeMap")}}, the interface of the returned object</li> + <li>Cross-browser compatibility considerations: on <a class="external" href="http://www.quirksmode.org/dom/w3c_core.html#attributes" title="http://www.quirksmode.org/dom/w3c_core.html#attributes">quirksmode</a></li> +</ul> diff --git a/files/zh-tw/web/api/element/classlist/index.html b/files/zh-tw/web/api/element/classlist/index.html new file mode 100644 index 0000000000..afa5b7c862 --- /dev/null +++ b/files/zh-tw/web/api/element/classlist/index.html @@ -0,0 +1,403 @@ +--- +title: Element.classList +slug: Web/API/Element/classList +translation_of: Web/API/Element/classList +--- +<div>{{APIRef("DOM")}}</div> + +<p><code><strong>Element.classList</strong></code> 唯讀屬性代表了該元素所擁有之類別屬性（<code>Class</code> {{Glossary("Attribute")}}）的即時更新集－{{domxref("DOMTokenList")}}。</p> + +<p>使用 <code>classList</code> 屬性是取得元素 <code>Class</code> 的一種便利方式，也可以透過 {{domxref("element.className")}} 來得到以空格分隔之 <code>Class</code> 清單字串。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">var <var>elementClasses</var> = elementNodeReference.classList; +</pre> + +<p><em>elementClasses</em> is a {{domxref("DOMTokenList")}} representing the class attribute of <em>elementNodeReference</em>. If the class attribute was not set or is empty <em>elementClasses.length</em> returns 0. <code>element.classList</code> itself is read-only, although you can modify it using the<code> add()</code> and <code>remove()</code> methods.</p> + +<h2 id="方法">方法</h2> + +<dl> + <dt>add( String [, String] )</dt> + <dd>Add specified class values. If these classes already exist in attribute of the element, then they are ignored.</dd> + <dt>remove( String [,String] )</dt> + <dd>Remove specified class values.</dd> + <dt><strong>item</strong> ( Number )</dt> + <dd>Return class value by index in collection.</dd> + <dt><strong>toggle</strong> ( String [, force] )</dt> + <dd>When only one argument is present: Toggle class value; i.e., if class exists then remove it and return false, if not, then add it and return true.<br> + When a second argument is present: If the second argument is true, add specified class value, and if it is false, remove it.</dd> + <dt>contains( String )</dt> + <dd>Checks if specified class value exists in class attribute of the element.</dd> +</dl> + +<h2 id="範例">範例</h2> + +<pre class="brush: js" dir="rtl">// div is an object reference to a <div> element with class="foo bar" +div.classList.remove("foo"); +div.classList.add("anotherclass"); + +// if visible is set remove it, otherwise add it +div.classList.toggle("visible"); + +// add/remove visible, depending on test conditional, i less than 10 +div.classList.toggle("visible", i < 10 ); + +alert(div.classList.contains("foo")); + +div.classList.add("foo","bar"); //add multiple classes</pre> + +<div class="note"> +<p>Versions of Firefox before 26 do not implement the use of several arguments in the add/remove/toggle methods. See <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=814014">https://bugzilla.mozilla.org/show_bug.cgi?id=814014</a></p> +</div> + +<h2 id="JavaScript_shim_for_other_implementations">JavaScript shim for other implementations</h2> + +<div class="note"><strong>Note:</strong> This shim does not work in Internet Explorer versions less than 8.</div> + +<pre class="brush: js">/* + * classList.js: Cross-browser full element.classList implementation. + * 2014-07-23 + * + * By Eli Grey, http://eligrey.com + * Public Domain. + * NO WARRANTY EXPRESSED OR IMPLIED. USE AT YOUR OWN RISK. + */ + +/*global self, document, DOMException */ + +/*! @source http://purl.eligrey.com/github/classList.js/blob/master/classList.js*/ + +if ("document" in self) { + +// Full polyfill for browsers with no classList support +if (!("classList" in document.createElement("_"))) { + +(function (view) { + +"use strict"; + +if (!('Element' in view)) return; + +var + classListProp = "classList" + , protoProp = "prototype" + , elemCtrProto = view.Element[protoProp] + , objCtr = Object + , strTrim = String[protoProp].trim || function () { + return this.replace(/^\s+|\s+$/g, ""); + } + , arrIndexOf = Array[protoProp].indexOf || function (item) { + var + i = 0 + , len = this.length + ; + for (; i < len; i++) { + if (i in this && this[i] === item) { + return i; + } + } + return -1; + } + // Vendors: please allow content code to instantiate DOMExceptions + , DOMEx = function (type, message) { + this.name = type; + this.code = DOMException[type]; + this.message = message; + } + , checkTokenAndGetIndex = function (classList, token) { + if (token === "") { + throw new DOMEx( + "SYNTAX_ERR" + , "An invalid or illegal string was specified" + ); + } + if (/\s/.test(token)) { + throw new DOMEx( + "INVALID_CHARACTER_ERR" + , "String contains an invalid character" + ); + } + return arrIndexOf.call(classList, token); + } + , ClassList = function (elem) { + var + trimmedClasses = strTrim.call(elem.getAttribute("class") || "") + , classes = trimmedClasses ? trimmedClasses.split(/\s+/) : [] + , i = 0 + , len = classes.length + ; + for (; i < len; i++) { + this.push(classes[i]); + } + this._updateClassName = function () { + elem.setAttribute("class", this.toString()); + }; + } + , classListProto = ClassList[protoProp] = [] + , classListGetter = function () { + return new ClassList(this); + } +; +// Most DOMException implementations don't allow calling DOMException's toString() +// on non-DOMExceptions. Error's toString() is sufficient here. +DOMEx[protoProp] = Error[protoProp]; +classListProto.item = function (i) { + return this[i] || null; +}; +classListProto.contains = function (token) { + token += ""; + return checkTokenAndGetIndex(this, token) !== -1; +}; +classListProto.add = function () { + var + tokens = arguments + , i = 0 + , l = tokens.length + , token + , updated = false + ; + do { + token = tokens[i] + ""; + if (checkTokenAndGetIndex(this, token) === -1) { + this.push(token); + updated = true; + } + } + while (++i < l); + + if (updated) { + this._updateClassName(); + } +}; +classListProto.remove = function () { + var + tokens = arguments + , i = 0 + , l = tokens.length + , token + , updated = false + , index + ; + do { + token = tokens[i] + ""; + index = checkTokenAndGetIndex(this, token); + while (index !== -1) { + this.splice(index, 1); + updated = true; + index = checkTokenAndGetIndex(this, token); + } + } + while (++i < l); + + if (updated) { + this._updateClassName(); + } +}; +classListProto.toggle = function (token, force) { + token += ""; + + var + result = this.contains(token) + , method = result ? + force !== true && "remove" + : + force !== false && "add" + ; + + if (method) { + this[method](token); + } + + if (force === true || force === false) { + return force; + } else { + return !result; + } +}; +classListProto.toString = function () { + return this.join(" "); +}; + +if (objCtr.defineProperty) { + var classListPropDesc = { + get: classListGetter + , enumerable: true + , configurable: true + }; + try { + objCtr.defineProperty(elemCtrProto, classListProp, classListPropDesc); + } catch (ex) { // IE 8 doesn't support enumerable:true + if (ex.number === -0x7FF5EC54) { + classListPropDesc.enumerable = false; + objCtr.defineProperty(elemCtrProto, classListProp, classListPropDesc); + } + } +} else if (objCtr[protoProp].__defineGetter__) { + elemCtrProto.__defineGetter__(classListProp, classListGetter); +} + +}(self)); + +} else { +// There is full or partial native classList support, so just check if we need +// to normalize the add/remove and toggle APIs. + +(function () { + "use strict"; + + var testElement = document.createElement("_"); + + testElement.classList.add("c1", "c2"); + + // Polyfill for IE 10/11 and Firefox <26, where classList.add and + // classList.remove exist but support only one argument at a time. + if (!testElement.classList.contains("c2")) { + var createMethod = function(method) { + var original = DOMTokenList.prototype[method]; + + DOMTokenList.prototype[method] = function(token) { + var i, len = arguments.length; + + for (i = 0; i < len; i++) { + token = arguments[i]; + original.call(this, token); + } + }; + }; + createMethod('add'); + createMethod('remove'); + } + + testElement.classList.toggle("c3", false); + + // Polyfill for IE 10 and Firefox <24, where classList.toggle does not + // support the second argument. + if (testElement.classList.contains("c3")) { + var _toggle = DOMTokenList.prototype.toggle; + + DOMTokenList.prototype.toggle = function(token, force) { + if (1 in arguments && !this.contains(token) === !force) { + return force; + } else { + return _toggle.call(this, token); + } + }; + + } + + testElement = null; +}()); + +} + +}</pre> + +<h2 id="規範">規範</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.html#dom-classlist", "Element.classList")}}</td> + <td>{{Spec2("HTML WHATWG")}}</td> + <td>Note within the HTML specification related to the {{htmlattrxref("class")}} attribute.</td> + </tr> + <tr> + <td>{{SpecName("DOM WHATWG", "#dom-element-classlist", "Element.classList")}}</td> + <td>{{Spec2("DOM WHATWG")}}</td> + <td>Initial definition</td> + </tr> + <tr> + <td>{{SpecName("DOM4", "#dom-element-classlist", "Element.classList")}}</td> + <td>{{Spec2("DOM4")}}</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>Edge</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>8.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1.9.2")}}</td> + <td>10<sup>[1]</sup></td> + <td>11.50</td> + <td>5.1</td> + </tr> + <tr> + <td>toggle method's second argument</td> + <td>24</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("24")}}</td> + <td>{{CompatNo}}<sup>[2]</sup></td> + <td>15</td> + <td>5.1</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>3.0</td> + <td>{{CompatGeckoMobile("1.9.2")}}</td> + <td>10</td> + <td>11.10</td> + <td>5.0</td> + </tr> + <tr> + <td>toggle method's second argument</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("24")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Not supported for SVG elements. See <a href="https://connect.microsoft.com/IE/feedback/details/1046039/classlist-not-working-on-svg-elements">a report at Microsoft about that</a>.<br> + [2] Internet Explorer never implemented this. See <a href="https://connect.microsoft.com/IE/feedback/details/878564/element-classlist-toggle-does-not-support-second-parameter">a report at Microsoft about that</a>.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("element.className")}}</li> + <li>{{domxref("DOMTokenList")}};</li> +</ul> diff --git a/files/zh-tw/web/api/element/click_event/index.html b/files/zh-tw/web/api/element/click_event/index.html new file mode 100644 index 0000000000..4c7044e4b3 --- /dev/null +++ b/files/zh-tw/web/api/element/click_event/index.html @@ -0,0 +1,205 @@ +--- +title: click +slug: Web/API/Element/click_event +tags: + - 待翻譯 +translation_of: Web/API/Element/click_event +--- +<p><code>click</code> 事件通常會在設備的按鈕（通常是滑鼠按鍵）點擊元素時執行。</p> + +<h2 id="基本資料">基本資料</h2> + +<dl> + <dt style="float: left; text-align: right; width: 120px;">詳述</dt> + <dd style="margin: 0 0 0 120px;"><a class="external" href="http://www.w3.org/TR/DOM-Level-3-Events/#event-type-click">DOM L3</a></dd> + <dt style="float: left; text-align: right; width: 120px;">介面</dt> + <dd style="margin: 0 0 0 120px;">{{domxref("MouseEvent")}}</dd> + <dt style="float: left; text-align: right; width: 120px;">Bubbles</dt> + <dd style="margin: 0 0 0 120px;">Yes</dd> + <dt style="float: left; text-align: right; width: 120px;">Cancelable</dt> + <dd style="margin: 0 0 0 120px;">Yes</dd> + <dt style="float: left; text-align: right; width: 120px;">Target</dt> + <dd style="margin: 0 0 0 120px;">網頁元素</dd> + <dt style="float: left; text-align: right; width: 120px;">Default Action</dt> + <dd style="margin: 0 0 0 120px;">Varies</dd> +</dl> + +<h2 id="Properties">Properties</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Property</th> + <th scope="col">Type</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>target</code> {{readonlyInline}}</td> + <td><a href="/en-US/docs/Web/API/EventTarget" title="EventTarget is an interface implemented by objects that can receive events and may have listeners for them."><code>EventTarget</code></a></td> + <td>The event target (the topmost target in the DOM tree).</td> + </tr> + <tr> + <td><code>type</code> {{readonlyInline}}</td> + <td><a href="/en-US/docs/Web/API/DOMString" title="DOMString is a UTF-16 String. As JavaScript already uses such strings, DOMString is mapped directly to a String."><code>DOMString</code></a></td> + <td>The type of event.</td> + </tr> + <tr> + <td><code>bubbles</code> {{readonlyInline}}</td> + <td><a href="/en-US/docs/Web/API/Boolean" title="The Boolean object is an object wrapper for a boolean value."><code>Boolean</code></a></td> + <td>Whether the event normally bubbles or not</td> + </tr> + <tr> + <td><code>cancelable</code> {{readonlyInline}}</td> + <td><a href="/en-US/docs/Web/API/Boolean" title="The Boolean object is an object wrapper for a boolean value."><code>Boolean</code></a></td> + <td>Whether the event is cancellable or not?</td> + </tr> + <tr> + <td><code>view</code> {{readonlyInline}}</td> + <td><a class="new" href="/en-US/docs/Web/API/WindowProxy" rel="nofollow" title="The documentation about this has not yet been written; please consider contributing!"><code>WindowProxy</code></a></td> + <td><a href="/en-US/docs/Web/API/Document/defaultView" title="In browsers, document.defaultView returns the window object associated with a document, or null if none is available."><code>document.defaultView</code></a> (<code>window</code> of the document)</td> + </tr> + <tr> + <td><code>detail</code> {{readonlyInline}}</td> + <td><code>long</code> (<code>float</code>)</td> + <td>A count of consecutive clicks that happened in a short amount of time, incremented by one.</td> + </tr> + <tr> + <td><code>currentTarget</code> {{readonlyInline}}</td> + <td>EventTarget</td> + <td>The node that had the event listener attached.</td> + </tr> + <tr> + <td><code>relatedTarget</code> {{readonlyInline}}</td> + <td>EventTarget</td> + <td>For <code>mouseover</code>, <code>mouseout</code>, <code>mouseenter</code> and <code>mouseleave</code> events: the target of the complementary event (the <code>mouseleave</code> target in the case of a <code>mouseenter</code> event). <code>null</code> otherwise.</td> + </tr> + <tr> + <td><code>screenX</code> {{readonlyInline}}</td> + <td>long</td> + <td>The X coordinate of the mouse pointer in global (screen) coordinates.</td> + </tr> + <tr> + <td><code>screenY</code> {{readonlyInline}}</td> + <td>long</td> + <td>The Y coordinate of the mouse pointer in global (screen) coordinates.</td> + </tr> + <tr> + <td><code>clientX</code> {{readonlyInline}}</td> + <td>long</td> + <td>The X coordinate of the mouse pointer in local (DOM content) coordinates.</td> + </tr> + <tr> + <td><code>clientY</code> {{readonlyInline}}</td> + <td>long</td> + <td>The Y coordinate of the mouse pointer in local (DOM content) coordinates.</td> + </tr> + <tr> + <td><code>button</code> {{readonlyInline}}</td> + <td>unsigned short</td> + <td>The button number that was pressed when the mouse event was fired: Left button=0, middle button=1 (if present), right button=2. For mice configured for left handed use in which the button actions are reversed the values are instead read from right to left.</td> + </tr> + <tr> + <td><code>buttons</code> {{readonlyInline}}</td> + <td>unsigned short</td> + <td>The buttons being pressed when the mouse event was fired: Left button=1, Right button=2, Middle (wheel) button=4, 4th button (typically, "Browser Back" button)=8, 5th button (typically, "Browser Forward" button)=16. If two or more buttons are pressed, returns the logical sum of the values. E.g., if Left button and Right button are pressed, returns 3 (=1 | 2). <a href="/en-US/docs/Web/API/MouseEvent">More info</a>.</td> + </tr> + <tr> + <td><code>mozPressure</code> {{readonlyInline}}</td> + <td>float</td> + <td>The amount of pressure applied to a touch or tabdevice when generating the event; this value ranges between 0.0 (minimum pressure) and 1.0 (maximum pressure).</td> + </tr> + <tr> + <td><code>ctrlKey</code> {{readonlyInline}}</td> + <td>boolean</td> + <td><code>true</code> if the control key was down when the event was fired. <code>false</code> otherwise.</td> + </tr> + <tr> + <td><code>shiftKey</code> {{readonlyInline}}</td> + <td>boolean</td> + <td><code>true</code> if the shift key was down when the event was fired. <code>false</code> otherwise.</td> + </tr> + <tr> + <td><code>altKey</code> {{readonlyInline}}</td> + <td>boolean</td> + <td><code>true</code> if the alt key was down when the event was fired. <code>false</code> otherwise.</td> + </tr> + <tr> + <td><code>metaKey</code> {{readonlyInline}}</td> + <td>boolean</td> + <td><code>true</code> if the meta key was down when the event was fired. <code>false</code> otherwise.</td> + </tr> + </tbody> +</table> + +<h2 id="範例">範例</h2> + +<pre class="brush: js"><div id="test"></div> + +<script> + document.getElementById("test").addEventListener("click", function( event ) { + // 在 “clicked div”顯示點擊次數 + event.target.innerHTML = "click count: " + event.detail; + }, false); +</script> +</pre> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<h3 id="Internet_Explorer">Internet Explorer</h3> + +<p>Internet Explorer 8 & 9 suffer from a bug where elements with a computed {{cssxref("background-color")}} of <a href="/en-US/docs/Web/CSS/color_value#transparent_keyword"><code>transparent</code></a> that are overlaid on top of other element(s) won't receive <code>click</code> events. Any <code>click</code> events will be fired at the underlying element(s) instead. See <a href="http://jsfiddle.net/YUKma/show/">this live example</a> for a demonstration.</p> + +<p>Known workarounds for this bug:</p> + +<ul> + <li>For IE9 only: + <ul> + <li>Set <code>{{cssxref("background-color")}}: <a href="/en-US/docs/Web/CSS/color_value#rgba()">rgba</a>(0,0,0,0)</code></li> + <li>Set <code>{{cssxref("opacity")}}: 0</code> and an explicit {{cssxref("background-color")}} other than <a href="/en-US/docs/Web/CSS/color_value#transparent_keyword"><code>transparent</code></a></li> + </ul> + </li> + <li>For IE8 and IE9: Set <code><a href="http://msdn.microsoft.com/en-us/library/ms532847(v=vs.85).aspx">filter</a>: alpha(opacity=0);</code> and an explicit {{cssxref("background-color")}} other than <a href="/en-US/docs/Web/CSS/color_value#transparent_keyword"><code>transparent</code></a></li> +</ul> + +<h3 id="Safari_Mobile">Safari Mobile</h3> + +<p>Safari Mobile 7.0+ (and likely earlier versions too) suffers from a bug where <code>click</code> events aren't fired on elements that aren't typically interactive (e.g. {{HTMLElement("div")}}) and which also don't have event listeners directly attached to the elements themselves (i.e. <a href="http://davidwalsh.name/event-delegate">event delegation</a> is being used). See <a href="http://jsfiddle.net/cvrhulu/k9t0sdnf/show/">this live example</a> for a demonstration. See also <a href="https://developer.apple.com/library/safari/documentation/appleapplications/reference/safariwebcontent/HandlingEvents/HandlingEvents.html#//apple_ref/doc/uid/TP40006511-SW6">Safari's docs on making elements clickable</a> and the <a href="https://developer.apple.com/library/safari/documentation/appleapplications/reference/safariwebcontent/HandlingEvents/HandlingEvents.html#//apple_ref/doc/uid/TP40006511-SW7">definition of "clickable element"</a>.</p> + +<p>Known workarounds for this bug:</p> + +<ul> + <li>Set {{cssxref("cursor")}}<code>: pointer;</code> on the element or any of its ancestors.</li> + <li>Add a dummy <code>onclick=""</code> attribute to the element or any of its ancestors up to but not including {{HTMLElement("body")}}.</li> + <li>Use a typically interactive element (e.g. {{HTMLElement("a")}}) instead of one that isn't typically interactive (e.g. {{HTMLElement("div")}}).</li> + <li>Stop using <code>click</code> <a href="http://davidwalsh.name/event-delegate">event delegation</a>.</li> +</ul> + +<p>Safari Mobile considers the following elements to be typically interactive (and thus they aren't affected by this bug):</p> + +<ul> + <li>{{HTMLElement("a")}} (but it must have an <code>href</code>)</li> + <li>{{HTMLElement("area")}} (but it must have an <code>href</code>)</li> + <li>{{HTMLElement("button")}}</li> + <li>{{HTMLElement("img")}}</li> + <li>{{HTMLElement("input")}}</li> + <li>{{HTMLElement("label")}} (but it must be associated with a form control)</li> + <li>{{HTMLElement("textarea")}}</li> + <li><em>This list is incomplete; you can help MDN by doing further testing/research and expanding it.</em></li> +</ul> + +<h2 id="關聯事件">關聯事件</h2> + +<ul> + <li>{{event("mousedown")}}</li> + <li>{{event("mouseup")}}</li> + <li>{{event("mousemove")}}</li> + <li>{{event("click")}}</li> + <li>{{event("dblclick")}}</li> + <li>{{event("mouseover")}}</li> + <li>{{event("mouseout")}}</li> + <li>{{event("mouseenter")}}</li> + <li>{{event("mouseleave")}}</li> + <li>{{event("contextmenu")}}</li> +</ul> diff --git a/files/zh-tw/web/api/element/clientheight/index.html b/files/zh-tw/web/api/element/clientheight/index.html new file mode 100644 index 0000000000..99ae4faf06 --- /dev/null +++ b/files/zh-tw/web/api/element/clientheight/index.html @@ -0,0 +1,62 @@ +--- +title: Element.clientHeight +slug: Web/API/Element/clientHeight +tags: + - API + - Reference +translation_of: Web/API/Element/clientHeight +--- +<p>{{ APIRef("DOM") }}</p> + +<p><code><strong>Element.clientHeight </strong></code>唯讀屬性會回傳元素內部高度（像素），包含 padding 但並未包含水平滾動條、border、margin。</p> + +<p><code>clientHeight</code> 可以被計算成 CSS <code>height</code> + CSS <code>padding</code> - 水平滾動條的高度（如果有顯示）</p> + +<div class="note"> +<p><strong>Note:</strong> 這個屬性會以四捨五入進位取整數. 如果要使用非整數值, 使用 {{ domxref("element.getBoundingClientRect()") }}.</p> +</div> + +<h2 id="Syntax_and_values" name="Syntax_and_values">表達式</h2> + +<pre class="syntaxbox">var <var>h</var> = <var>element</var>.clientHeight;</pre> + +<p><code><var>h</var></code> 代表元素高度(pixels)的正整數.</p> + +<h2 id="Example" name="Example">範例</h2> + +<p> </p> + +<p> <img alt="Image:Dimensions-client.png" class="internal" src="/@api/deki/files/185/=Dimensions-client.png"></p> + + +<h2 id="Specification" name="Specification">規範</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">註</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{SpecName('CSSOM View', '#dom-element-clientheight', 'clientHeight')}}</td> + <td>{{Spec2('CSSOM View')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h3 id="Notes" name="Notes">註</h3> + +<p><code>clientHeight</code> 是在 the Internet Explorer 物件介紹的屬性.</p> + +<h2 id="See_Also" name="See_Also">參見</h2> + +<ul> + <li>{{domxref("HTMLElement.offsetHeight")}}</li> + <li>{{domxref("Element.scrollHeight")}}</li> + <li><a href="/en-US/docs/Determining_the_dimensions_of_elements">Determining the dimensions of elements</a></li> + <li><a href="https://docs.microsoft.com/en-us/previous-versions//hh781509(v=vs.85)">MSDN Measuring Element Dimension and Location</a></li> +</ul> diff --git a/files/zh-tw/web/api/element/getattribute/index.html b/files/zh-tw/web/api/element/getattribute/index.html new file mode 100644 index 0000000000..e5b7a1c27e --- /dev/null +++ b/files/zh-tw/web/api/element/getattribute/index.html @@ -0,0 +1,71 @@ +--- +title: Element.getAttribute() +slug: Web/API/Element/getAttribute +translation_of: Web/API/Element/getAttribute +--- +<div>{{APIRef("DOM")}}</div> + +<h2 id="Summary" name="Summary">摘要</h2> + +<p><span class="seoSummary"><code>getAttribute()</code> 函式會回傳該網頁元素的屬性</span>。 如果該屬性不存在，其回傳值會是<code>null或</code> <code>""</code> (空字串); 詳見 {{Anch("Notes")}} 。</p> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox"><em>var </em><code><em>attribute</em></code> = element.getAttribute(<code><em>attributeName</em></code>); +</pre> + +<p>where</p> + +<ul> + <li><code><em>attribute</em></code> is a string containing the value of <code><em>attributeName</em></code>.</li> + <li><code><em>attributeName</em></code> is the name of the attribute whose value you want to get.</li> +</ul> + +<h2 id="Example" name="Example">Example</h2> + +<pre class="brush:js">var div1 = document.getElementById("div1"); +var align = div1.getAttribute("align"); + +alert(align); // shows the value of align for the element with id="div1"</pre> + +<h2 id="Notes" name="Notes">Notes</h2> + +<p>When called on an HTML element in a DOM flagged as an HTML document, <code>getAttribute()</code> lower-cases its argument before proceeding.</p> + +<p>Essentially all web browsers (Firefox, Internet Explorer, recent versions of Opera, Safari, Konqueror, and iCab, as a non-exhaustive list) return <code>null</code> when the specified attribute does not exist on the specified element and this is what <a href="http://dom.spec.whatwg.org/#dom-element-getattribute" title="http://dom.spec.whatwg.org/#dom-element-getattribute">the current DOM specification draft</a> specifies. The old DOM 3 Core specification, on the other hand, says that the correct return value in this case is actually the <em>empty string</em>, and some DOM implementations implement this behavior. The implementation of getAttribute in XUL (Gecko) actually follows the DOM 3 Core specification and returns an empty string. Consequently, you should use {{domxref("element.hasAttribute()")}} to check for an attribute's existence prior to calling <code>getAttribute()</code> if it is possible that the requested attribute does not exist on the specified element.</p> + +<h2 id="Browser_compatibility">Browser compatibility</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>29</td> + <td>23</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>6</td> + </tr> + </tbody> +</table> +</div> + +<div>{{DOMAttributeMethods}}</div> + +<h2 id="Specification" name="Specification">Specification</h2> + +<ul> + <li><a class="external" href="http://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-666EE0F9">DOM Level 2 Core: getAttribute</a> (introduced in <a class="external" href="http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#method-getAttribute">DOM Level 1 Core</a>)</li> + <li><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#apis-in-html-documents">HTML 5: APIs in HTML documents</a></li> +</ul> diff --git a/files/zh-tw/web/api/element/index.html b/files/zh-tw/web/api/element/index.html new file mode 100644 index 0000000000..d363baeead --- /dev/null +++ b/files/zh-tw/web/api/element/index.html @@ -0,0 +1,674 @@ +--- +title: Element +slug: Web/API/Element +tags: + - API + - DOM + - DOM Reference + - Element + - NeedsTranslation + - TopicStub + - Élément(2) +translation_of: Web/API/Element +--- +<p>{{ APIRef("DOM") }}</p> + +<p><span class="seoSummary"><strong><code>Element</code></strong> 介面表示了一個在 {{domxref("Document")}} 中的物件，其描述了各類型元素的共同屬性與方法，<code>Element</code> 的子介面則定義了不同類型元素的具體行為並增加額外的功能。</span>例如 {{domxref("HTMLElement")}} 為所有 HTML 元素的基礎介面，而 {{domxref("SVGElement")}} 則是定義所有 SVG 元素的介面。</p> + +<p>在 Web 領域之外，如 XUL 語言也能藉由 <code>XULElement</code> 介面來繼承 <code>Element</code>。</p> + +<p>{{InheritanceDiagram}}</p> + +<h2 id="Properties" name="Properties">屬性</h2> + +<p><em>Inherits properties from its parent interface, {{domxref("Node")}}, and by extension that interface's parent, {{domxref("EventTarget")}}. It implements the properties of {{domxref("ParentNode")}}, {{domxref("ChildNode")}}, {{domxref("NonDocumentTypeChildNode")}}, </em>and {{domxref("Animatable")}}.</p> + +<dl> + <dt>{{ domxref("Element.assignedSlot")}} {{experimental_inline}} {{readOnlyInline}}</dt> + <dd>Returns the {{domxref("HTMLSlotElement")}} interface associated with the element.</dd> + <dt>{{ domxref("Element.attributes") }} {{readOnlyInline}}</dt> + <dd>Returns a {{ domxref("NamedNodeMap") }} object containing the assigned attributes of the corresponding HTML element.</dd> + <dt>{{ domxref("Element.classList") }} {{readOnlyInline}}</dt> + <dd>Returns a {{ domxref("DOMTokenList") }} containing the list of class attributes.</dd> + <dt>{{ domxref("Element.className") }}</dt> + <dd>Is a {{domxref("DOMString")}} representing the class of the element.</dd> + <dt>{{ domxref("Element.clientHeight") }} {{experimental_inline}} {{readOnlyInline}}</dt> + <dd>Returns a {{jsxref("Number")}} representing the inner height of the element.</dd> + <dt>{{ domxref("Element.clientLeft") }} {{experimental_inline}} {{readOnlyInline}}</dt> + <dd>Returns a {{jsxref("Number")}} representing the width of the left border of the element.</dd> + <dt>{{ domxref("Element.clientTop") }} {{experimental_inline}} {{readOnlyInline}}</dt> + <dd>Returns a {{jsxref("Number")}} representing the width of the top border of the element.</dd> + <dt>{{ domxref("Element.clientWidth") }} {{experimental_inline}} {{readOnlyInline}}</dt> + <dd>Returns a {{jsxref("Number")}} representing the inner width of the element.</dd> + <dt>{{domxref("Element.computedName")}} {{readOnlyInline}}</dt> + <dd>Returns a {{domxref("DOMString")}} containing the label exposed to accessibility.</dd> + <dt>{{domxref("Element.computedRole")}} {{readOnlyInline}}</dt> + <dd>Returns a {{domxref("DOMString")}} containing the ARIA role that has been applied to a particular element.</dd> + <dt>{{ domxref("Element.id") }}</dt> + <dd>Is a {{domxref("DOMString")}} representing the id of the element.</dd> + <dt>{{ domxref("Element.innerHTML") }}</dt> + <dd>Is a {{domxref("DOMString")}} representing the markup of the element's content.</dd> + <dt>{{ domxref("Element.localName") }} {{readOnlyInline}}</dt> + <dd>A {{domxref("DOMString")}} representing the local part of the qualified name of the element.</dd> + <dt>{{domxref("Element.namespaceURI")}} {{readonlyInline}}</dt> + <dd>The namespace URI of the element, or <code>null</code> if it is no namespace. + <div class="note"> + <p><strong>Note:</strong> In Firefox 3.5 and earlier, HTML elements are in no namespace. In later versions, HTML elements are in the <code><a class="linkification-ext external" href="http://www.w3.org/1999/xhtml" title="Linkification: http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</a></code> namespace in both HTML and XML trees. {{ gecko_minversion_inline("1.9.2") }}</p> + </div> + </dd> + <dt>{{ domxref("NonDocumentTypeChildNode.nextElementSibling") }} {{readOnlyInline}}</dt> + <dd>Is a {{ domxref("Element") }}, the element immediately following the given one in the tree, or <code>null</code> if there's no sibling node.</dd> + <dt>{{ domxref("Element.outerHTML") }} {{experimental_inline}}</dt> + <dd>Is a {{domxref("DOMString")}} representing the markup of the element including its content. When used as a setter, replaces the element with nodes parsed from the given string.</dd> + <dt>{{ domxref("Element.prefix") }} {{readOnlyInline}}</dt> + <dd>A {{domxref("DOMString")}} representing the namespace prefix of the element, or <code>null</code> if no prefix is specified.</dd> + <dt>{{ domxref("NonDocumentTypeChildNode.previousElementSibling") }} {{readOnlyInline}}</dt> + <dd>Is a {{ domxref("Element") }}, the element immediately preceding the given one in the tree, or <code>null</code> if there is no sibling element.</dd> + <dt>{{ domxref("Element.scrollHeight") }} {{experimental_inline}} {{readOnlyInline}}</dt> + <dd>Returns a {{jsxref("Number")}} representing the scroll view height of an element.</dd> + <dt>{{ domxref("Element.scrollLeft") }} {{experimental_inline}}</dt> + <dd>Is a {{jsxref("Number")}} representing the left scroll offset of the element.</dd> + <dt>{{ domxref("Element.scrollLeftMax") }} {{non-standard_inline}} {{readOnlyInline}}</dt> + <dd>Returns a {{jsxref("Number")}} representing the maximum left scroll offset possible for the element.</dd> + <dt>{{ domxref("Element.scrollTop") }} {{experimental_inline}}</dt> + <dd>Is a {{jsxref("Number")}} representing the top scroll offset the an element.</dd> + <dt>{{ domxref("Element.scrollTopMax") }} {{non-standard_inline}} {{readOnlyInline}}</dt> + <dd>Returns a {{jsxref("Number")}} representing the maximum top scroll offset possible for the element.</dd> + <dt>{{ domxref("Element.scrollWidth") }} {{experimental_inline}} {{readOnlyInline}}</dt> + <dd>Returns a {{jsxref("Number")}} representing the scroll view width of the element.</dd> + <dt>{{domxref("Element.shadowRoot") }} {{experimental_inline}} {{readOnlyInline}}</dt> + <dd>Returns the youngest shadow root that is hosted by the element.</dd> + <dt>{{domxref("Element.slot")}} {{experimental_inline}}</dt> + <dd>Returns the name of the shadow DOM slot attatched to the element. A slot is a placeholder inside a web component that users can fill with their own markup.</dd> + <dt>{{domxref("Element.tabStop")}} {{non-standard_inline}}</dt> + <dd>Is a {{jsxref("Boolean")}} indicating if the element can receive input focus via the tab key.</dd> + <dt>{{ domxref("Element.tagName") }} {{readOnlyInline}}</dt> + <dd>Returns a {{domxref("String")}} with the name of the tag for the given element.</dd> + <dt>{{ domxref("Element.undoManager")}} {{experimental_inline}} {{readOnlyInline}}</dt> + <dd>Returns the {{domxref("UndoManager")}} associated with the element.</dd> + <dt>{{ domxref("Element.undoScope")}} {{experimental_inline}}</dt> + <dd>Is a {{jsxref("Boolean")}} indicating if the element is an undo scope host, or not.</dd> +</dl> + +<div class="note"> +<p><strong>Note:</strong> DOM Level 3 defined <code>namespaceURI</code>, <code>localName</code> and <code>prefix</code> on the {{domxref("Node")}} interface. In DOM4 they were moved to <code>Element</code>.</p> + +<p>This change is implemented in Chrome since version 46.0 and Firefox since version 48.0.</p> +</div> + +<h3 id="Handlers" name="Handlers">事件處理器</h3> + +<dl> + <dt>{{ domxref("Element.ongotpointercapture") }}</dt> + <dd>Returns the event handler for the {{event("gotpointercapture")}} event type.</dd> + <dt>{{ domxref("Element.onlostpointercapture") }}</dt> + <dd>Returns the event handler for the {{event("lostpointercapture")}} event type.</dd> + <dt>{{ domxref("Element.onwheel") }} {{ non-standard_inline() }}</dt> + <dd>Returns the event handling code for the <code>wheel</code> event.</dd> +</dl> + +<h2 id="Methods" name="Methods">方法</h2> + +<p><em>Inherits methods from its parents {{domxref("Node")}}, and its own parent, {{domxref("EventTarget")}}<em>, and implements those of {{domxref("ParentNode")}}, {{domxref("ChildNode")}}<em>, {{domxref("NonDocumentTypeChildNode")}}, </em></em>and {{domxref("Animatable")}}.</em></p> + +<dl> + <dt>{{ domxref("EventTarget.addEventListener()") }}</dt> + <dd>Registers an event handler to a specific event type on the element.</dd> + <dt>{{domxref("Element.attachShadow()")}} {{experimental_inline}}</dt> + <dd>Attatches a shadow DOM tree to the specified element and returns a reference to its {{domxref("ShadowRoot")}}.</dd> + <dt>{{domxref("Element.animate()")}} {{experimental_inline}}</dt> + <dd>A shortcut method to create and run an animation on an element. Returns the created Animation object instance.</dd> + <dt>{{ domxref("Element.closest()")}} {{experimental_inline}}</dt> + <dd>Returns the {{domxref("Element")}}, descendant of this element (or this element itself), that is the closest ancestor of the elements selected by the selectors given in parameter.</dd> + <dt>{{ domxref("Element.createShadowRoot()")}} {{experimental_inline}} {{deprecated_inline()}}</dt> + <dd>Creates a <a href="/en-US/docs/Web/Web_Components/Shadow_DOM">shadow DOM</a> on on the element, turning it into a shadow host. Returns a {{domxref("ShadowRoot")}}.</dd> + <dt>{{ domxref("EventTarget.dispatchEvent()") }}</dt> + <dd>Dispatches an event to this node in the DOM and returns a {{jsxref("Boolean")}} that indicates that at least one handler has not canceled it.</dd> + <dt>{{domxref("Element.find()")}}{{experimental_inline}}</dt> + <dd>...</dd> + <dt>{{domxref("Element.findAll()")}}{{experimental_inline}}</dt> + <dd>...</dd> + <dt>{{domxref("Element.getAnimations()")}} {{experimental_inline}}</dt> + <dd>Returns an array of Animation objects currently active on the element.</dd> + <dt>{{ domxref("Element.getAttribute()") }}</dt> + <dd>Retrieves the value of the named attribute from the current node and returns it as an {{jsxref("Object")}}.</dd> + <dt>{{ domxref("Element.getAttributeNames()") }}</dt> + <dd> </dd> + <dt>{{ domxref("Element.getAttributeNS()") }}</dt> + <dd>Retrieves the value of the attribute with the specified name and namespace, from the current node and returns it as an {{jsxref("Object")}}.</dd> + <dt>{{ domxref("Element.getAttributeNode()") }} {{obsolete_inline}}</dt> + <dd>Retrieves the node representation of the named attribute from the current node and returns it as an {{ domxref("Attr") }}.</dd> + <dt>{{ domxref("Element.getAttributeNodeNS()") }} {{obsolete_inline}}</dt> + <dd>Retrieves the node representation of the attribute with the specified name and namespace, from the current node and returns it as an {{ domxref("Attr") }}.</dd> + <dt>{{ domxref("Element.getBoundingClientRect()") }}</dt> + <dd>...</dd> + <dt>{{ domxref("Element.getClientRects()") }}</dt> + <dd>Returns a collection of rectangles that indicate the bounding rectangles for each line of text in a client.</dd> + <dt>{{domxref("Element.getDestinationInsertionPoints()")}} {{experimental_inline}}</dt> + <dd>…</dd> + <dt>{{ domxref("Element.getElementsByClassName()") }}</dt> + <dd>Returns a live {{ domxref("HTMLCollection") }} that contains all descendants of the current element that possess the list of classes given in the parameter.</dd> + <dt>{{ domxref("Element.getElementsByTagName()") }}</dt> + <dd>Returns a live {{ domxref("HTMLCollection") }} containing all descendant elements, of a particular tag name, from the current element.</dd> + <dt>{{ domxref("Element.getElementsByTagNameNS()") }}</dt> + <dd>Returns a live {{ domxref("HTMLCollection") }} containing all descendant elements, of a particular tag name and namespace, from the current element.</dd> + <dt>{{ domxref("Element.hasAttribute()") }}</dt> + <dd>Returns a {{jsxref("Boolean")}} indicating if the element has the specified attribute or not.</dd> + <dt>{{ domxref("Element.hasAttributeNS()") }}</dt> + <dd>Returns a {{jsxref("Boolean")}} indicating if the element has the specified attribute, in the specified namespace, or not.</dd> + <dt>{{ domxref("Element.hasAttributes()") }}</dt> + <dd>Returns a {{jsxref("Boolean")}} indicating if the element has one or more HTML attributes present.</dd> + <dt>{{ domxref("Element.insertAdjacentElement") }} {{experimental_inline}}</dt> + <dd>Inserts a given element node at a given position relative to the element it is invoked upon.</dd> + <dt>{{ domxref("Element.insertAdjacentHTML") }} {{experimental_inline}}</dt> + <dd>Parses the text as HTML or XML and inserts the resulting nodes into the tree in the position given.</dd> + <dt>{{ domxref("Element.insertAdjacentText") }} {{experimental_inline}}</dt> + <dd>Inserts a given text node at a given position relative to the element it is invoked upon.</dd> + <dt>{{ domxref("Element.matches()") }}<code> </code>{{experimental_inline}}</dt> + <dd>Returns a {{jsxref("Boolean")}} indicating whether or not the element would be selected by the specified selector string.</dd> + <dt>{{ domxref("Element.querySelector()") }}</dt> + <dd>Returns the first {{ domxref("Node") }} which matches the specified selector string relative to the element.</dd> + <dt>{{ domxref("Element.querySelectorAll") }}</dt> + <dd>Returns a {{ domxref("NodeList") }} of nodes which match the specified selector string relative to the element.</dd> + <dt>{{ domxref("Element.releasePointerCapture")}}</dt> + <dd>Releases (stops) pointer capture that was previously set for a specific {{domxref("PointerEvent","pointer event")}}.</dd> + <dt>{{domxref("ChildNode.remove()")}} {{experimental_inline}}</dt> + <dd>Removes the element from the children list of its parent.</dd> + <dt>{{ domxref("Element.removeAttribute()") }}</dt> + <dd>Removes the named attribute from the current node.</dd> + <dt>{{ domxref("Element.removeAttributeNS()") }}</dt> + <dd>Removes the attribute with the specified name and namespace, from the current node.</dd> + <dt>{{ domxref("Element.removeAttributeNode()") }} {{obsolete_inline}}</dt> + <dd>Removes the node representation of the named attribute from the current node.</dd> + <dt>{{ domxref("EventTarget.removeEventListener()") }}</dt> + <dd>Removes an event listener from the element.</dd> + <dt>{{ domxref("Element.requestFullscreen()") }} {{experimental_inline}}</dt> + <dd>Asynchronously asks the browser to make the element full-screen.</dd> + <dt>{{ domxref("Element.requestPointerLock()")}} {{experimental_inline}}</dt> + <dd>Allows to asynchronously ask for the pointer to be locked on the given element.</dd> +</dl> + +<dl> + <dt>{{ domxref("Element.scrollIntoView()") }} {{experimental_inline}}</dt> + <dd>Scrolls the page until the element gets into the view.</dd> + <dt>{{ domxref("Element.setAttribute()") }}</dt> + <dd>Sets the value of a named attribute of the current node.</dd> + <dt>{{ domxref("Element.setAttributeNS()") }}</dt> + <dd>Sets the value of the attribute with the specified name and namespace, from the current node.</dd> + <dt>{{ domxref("Element.setAttributeNode()") }} {{obsolete_inline}}</dt> + <dd>Sets the node representation of the named attribute from the current node.</dd> + <dt>{{ domxref("Element.setAttributeNodeNS()") }} {{obsolete_inline}}</dt> + <dd>Setw the node representation of the attribute with the specified name and namespace, from the current node.</dd> + <dt>{{ domxref("Element.setCapture()") }} {{non-standard_inline}}</dt> + <dd>Sets up mouse event capture, redirecting all mouse events to this element.</dd> + <dt>{{domxref("Element.setPointerCapture()")}}</dt> + <dd>Designates a specific element as the capture target of future {{domxref("PointerEvent","pointer events")}}.</dd> +</dl> + +<h2 id="規範">規範</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('Shadow DOM')}}</td> + <td>{{Spec2('Shadow DOM')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("Web Animations", '', '')}}</td> + <td>{{Spec2("Web Animations")}}</td> + <td>Added the <code>getAnimations()</code> method.</td> + </tr> + <tr> + <td>{{SpecName('Undo Manager', '', 'Element')}}</td> + <td>{{Spec2('Undo Manager')}}</td> + <td>Added the <code>undoScope</code> and <code>undoManager</code> properties.</td> + </tr> + <tr> + <td>{{SpecName('Pointer Events 2', '#extensions-to-the-element-interface', 'Element')}}</td> + <td>{{Spec2('Pointer Events 2')}}</td> + <td>Added the following event handlers: <code>ongotpointercapture</code> and <code>onlostpointercapture</code>.<br> + Added the following methods: <code>setPointerCapture()</code> and <code>releasePointerCapture()</code>.</td> + </tr> + <tr> + <td>{{SpecName('Pointer Events', '#extensions-to-the-element-interface', 'Element')}}</td> + <td>{{Spec2('Pointer Events')}}</td> + <td>Added the following event handlers: <code>ongotpointercapture</code> and <code>onlostpointercapture</code>.<br> + Added the following methods: <code>setPointerCapture()</code> and <code>releasePointerCapture()</code>.</td> + </tr> + <tr> + <td>{{SpecName('Selectors API Level 2', '#interface-definitions', 'Element')}}</td> + <td>{{Spec2('Selectors API Level 2')}}</td> + <td>Added the following methods:<code> matches()</code> (implemented as <code>mozMatchesSelector()</code>), <code>find()</code>, <code>findAll()</code>.</td> + </tr> + <tr> + <td>{{SpecName('Selectors API Level 1', '#interface-definitions', 'Element')}}</td> + <td>{{Spec2('Selectors API Level 1')}}</td> + <td>Added the following methods: <code>querySelector()</code> and <code>querySelectorAll()</code>.</td> + </tr> + <tr> + <td>{{SpecName('Pointer Lock', 'index.html#element-interface', 'Element')}}</td> + <td>{{Spec2('Pointer Lock')}}</td> + <td>Added the <code>requestPointerLock()</code> method.</td> + </tr> + <tr> + <td>{{SpecName('Fullscreen', '#api', 'Element')}}</td> + <td>{{Spec2('Fullscreen')}}</td> + <td>Added the <code>requestFullscreen()</code> method.</td> + </tr> + <tr> + <td>{{SpecName('DOM Parsing', '#extensions-to-the-element-interface', 'Element')}}</td> + <td>{{Spec2('DOM Parsing')}}</td> + <td>Added the following properties: <code>innerHTML</code>, and <code>outerHTML</code>.<br> + Added the following method: <code>insertAdjacentHTML()</code>.</td> + </tr> + <tr> + <td>{{SpecName('CSSOM View', '#extensions-to-the-element-interface', 'Element')}}</td> + <td>{{Spec2('CSSOM View')}}</td> + <td>Added the following properties: <code>scrollTop</code>, <code>scrollLeft</code>, <code>scrollWidth</code>, <code>scrollHeight</code>, <code>clientTop</code>, <code>clientLeft</code>, <code>clientWidth</code>, and <code>clientHeight</code>.<br> + Added the following methods: <code>getClientRects()</code>, <code>getBoundingClientRect()</code>, and <code>scrollIntoView()</code>.</td> + </tr> + <tr> + <td>{{SpecName('Element Traversal', '#ecmascript-bindings', 'Element')}}</td> + <td>{{Spec2('Element Traversal')}}</td> + <td>Added inheritance of the {{domxref("ElementTraversal")}} interface.</td> + </tr> + <tr> + <td>{{SpecName('DOM WHATWG', '#interface-element', 'Element')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>Removed the following methods: <code>closest()</code>, <code>setIdAttribute()</code>, <code>setIdAttributeNS()</code>, and <code>setIdAttributeNode()</code>.<br> + Removed the <code>schemaTypeInfo</code> property.<br> + Modified the return value of <code>getElementsByTag()</code> and <code>getElementsByTagNS()</code>.<br> + Moved <code>hasAttributes()</code> from the <code>Node</code> interface to this one.<br> + Inserted <code>insertAdjacentElement()</code> and <code>insertAdjacentText()</code>.</td> + </tr> + <tr> + <td>{{SpecName('DOM3 Core', 'core.html#ID-745549614', 'Element')}}</td> + <td>{{Spec2('DOM3 Core')}}</td> + <td>Added the following methods: <code>setIdAttribute()</code>, <code>setIdAttributeNS()</code>, and <code>setIdAttributeNode()</code>. These methods were never implemented and have been removed in later specifications.<br> + Added the <code>schemaTypeInfo</code> property. This property was never implemented and has been removed in later specifications.</td> + </tr> + <tr> + <td>{{SpecName('DOM2 Core', 'core.html#ID-745549614', 'Element')}}</td> + <td>{{Spec2('DOM2 Core')}}</td> + <td>The <code>normalize()</code> method has been moved to {{domxref("Node")}}.</td> + </tr> + <tr> + <td>{{SpecName('DOM1', 'level-one-core.html#ID-745549614', 'Element')}}</td> + <td>{{Spec2('DOM1')}}</td> + <td>Initial definition.</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>1.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>1.0</td> + </tr> + <tr> + <td><code>children</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1.9")}}</td> + <td>7.0 with a significant bug [1]<br> + 9.0 according to the spec</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>childElementCount</code>, <code>nextElementSibling</code>, <code>previousElementSibling</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>firstElementChild</code>, <code>lastElementChild</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1.9")}}</td> + <td>9.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>classList</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1.9.2")}}</td> + <td> </td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>outerHTML</code> {{experimental_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("11")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>clientLeft</code>, <code>clientTop</code> {{experimental_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>getBoundingClientRect()</code>, <code>getClientRects()</code> {{experimental_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1.9")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>querySelector()</code>, <code>querySelectorAll()</code></td> + <td>1.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>8.0</td> + <td>10.0</td> + <td>3.2 (525.3)</td> + </tr> + <tr> + <td><code>insertAdjacentHTML()</code> {{experimental_inline}}</td> + <td>1.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("8")}}</td> + <td>4.0</td> + <td>7.0</td> + <td>4.0 (527)</td> + </tr> + <tr> + <td><code>setCapture() </code>{{non-standard_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop("2")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>oncopy</code>, <code>oncut</code>, <code>onpaste</code> {{non-standard_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop("1.9")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td> </td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>onwheel</code> {{non-standard_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("17")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>ongotpointercapture</code>, <code>onlostpointercapture</code>, <code>setPointerCapture()</code>, and <code>releasePointerCapture()</code></td> + <td>{{CompatChrome(52.0)}} [4]</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}} <sup>[3]</sup></td> + <td>10.0</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>matches()</code> {{experimental_inline}}</td> + <td>{{CompatVersionUnknown}} with the non-standard name <code>webkitMatchesSelector</code></td> + <td>{{CompatVersionUnknown}} {{property_prefix("webkit")}} {{property_prefix("ms")}}</td> + <td>{{CompatGeckoDesktop("1.9.2")}} with the non-standard name <code>mozMatchesSelector</code><br> + {{CompatGeckoDesktop("34")}} with the standard name</td> + <td>9.0 with the non-standard name <code>msMatchesSelector</code></td> + <td>11.5 with the non-standard name <code>oMatchesSelector</code><br> + 15.0 with the non-standard name <code>webkitMatchesSelector</code></td> + <td>5.0 with the non-standard name <code>webkitMatchesSelector</code></td> + </tr> + <tr> + <td><code>find()</code> and <code>findAll()</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>requestPointerLock()</code></td> + <td>16.0 {{property_prefix("webkit")}}, behind an about:flags<br> + 22.0 {{property_prefix("webkit")}} (with special cases, progressively lifted see [2])</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("14")}}{{property_prefix("moz")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>requestFullscreen()</code></td> + <td>14.0 {{property_prefix("webkit")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("10")}} {{property_prefix("moz")}}</td> + <td>11.0 {{property_prefix("ms")}}</td> + <td>12.10<br> + 15.0 {{property_prefix("webkit")}}</td> + <td>5.1 {{property_prefix("webkit")}}</td> + </tr> + <tr> + <td><code>undoManager</code> and <code>undoScope</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}} (behind the <code>dom.undo_manager.enabled</code> pref)</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>attributes</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop("22")}}<br> + Before this it was available via the {{domxref("Node")}} interface that any <code>element</code> inherits.</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>scrollTopMax()</code> and <code>scrollLeftMax()</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop("16")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>closest()</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("35")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>hasAttributes()</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop("1.0")}} (on the {{domxref("Node")}} interface)<br> + {{CompatGeckoDesktop("35")}} (on this interface</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>insertAdjacentElement()</code>, <code>insertAdjacentText()</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop("48.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>assignedSlot</code>, <code>attatchShadow</code>, <code>shadowRoot</code>, and <code>slot</code></td> + <td>{{CompatChrome(53)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>computedRole</code> and <code>computedName</code></td> + <td>{{CompatChrome(41)}}[4]</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>28[4]</td> + <td>{{CompatUnknown}}</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>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + <th>Chrome for Android</th> + </tr> + <tr> + <td>Basic support</td> + <td>1.0</td> + <td> </td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("1")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>1.0</td> + <td> </td> + </tr> + <tr> + <td><code>scrollTopMax()</code> and <code>scrollLeftMax()</code></td> + <td>{{CompatNo}}</td> + <td> </td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile("16")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td> </td> + </tr> + <tr> + <td><code>closest()</code></td> + <td>{{CompatUnknown}}</td> + <td> </td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("35")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td> </td> + </tr> + <tr> + <td><code>hasAttributes()</code></td> + <td>{{CompatVersionUnknown}}</td> + <td> </td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile("1.0")}} (on the {{domxref("Node")}} interface)<br> + {{CompatGeckoMobile("35")}} (on this interface</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td> </td> + </tr> + <tr> + <td><code>insertAdjacentElement()</code>, <code>insertAdjacentText()</code></td> + <td>{{CompatVersionUnknown}}</td> + <td> </td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("48.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td> </td> + </tr> + <tr> + <td><code>assignedSlot</code>, <code>attatchShadow</code>, <code>shadowRoot</code>, and <code>slot</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatChrome(53.0)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatChrome(53)}}</td> + </tr> + <tr> + <td><code>computedRole</code> and <code>computedName</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>28[4]</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Internet Explorer 7 and 8 incorrectly return the comments as part of the children of an Element. This is fixed in Internet Explorer 9 and later.</p> + +<p>[2] Chrome 16 allowed <code>webkitRequestPointerLock()</code> only in fullscreen; Chrome 21 for trusted web site (permission asked); Chrome 22 allowed it by default for all same-origin document; Chrome 23 allowed it in sandboxed {{HTMLElement("iframe")}} if the non-standard value <code>webkit-allow-pointer-lock</code> is set to the {{htmlattrxref("sandbox", "iframe")}} attribute.</p> + +<p>[3] Implementation withdrawn. See {{Bug("1166347")}}.</p> + +<p>[4] Behind a flag.</p> diff --git a/files/zh-tw/web/api/element/innerhtml/index.html b/files/zh-tw/web/api/element/innerhtml/index.html new file mode 100644 index 0000000000..df002176e4 --- /dev/null +++ b/files/zh-tw/web/api/element/innerhtml/index.html @@ -0,0 +1,215 @@ +--- +title: Element.innerHTML +slug: Web/API/Element/innerHTML +tags: + - 元素組件 + - 注譯 + - 裏HTML + - 裏超文本 +translation_of: Web/API/Element/innerHTML +--- +<div>{{APIRef("DOM")}}</div> + + + +<p> <a href="/zh-TW/docs/Glossary/Element">Element</a> 的「innerHTML」屬性獲取或設置元素中包含的HTML或XML標記。</p> + +<div class="note"><strong>Note: </strong>如{{HTMLElement("div")}}, {{HTMLElement("span")}}, or {{HTMLElement("noembed")}} 節點有包含字符（＆），（<）或（>），innerHTML分別地回傳這些字符成為HTML的<code>“&” </code>，<code>“<” </code>和<code> “>” </code>。 使用 <code>Node.textContent</code> 得到的這些文本節點的內容的原始拷貝件。</div> + +<p>To insert the HTML into the document rather than replace the contents of an element, use the method {{domxref("Element.insertAdjacentHTML", "insertAdjacentHTML()")}}.</p> + +<h2 id="Syntax">Syntax</h2> + +<pre class="syntaxbox notranslate">const <var>content</var> = <var>element</var>.innerHTML; + +<var>element</var>.innerHTML = <var>htmlString</var>; +</pre> + +<h3 id="Value">Value</h3> + +<p>A {{domxref("DOMString")}} containing the HTML serialization of the element's descendants. Setting the value of <code>innerHTML</code> removes all of the element's descendants and replaces them with nodes constructed by parsing the HTML given in the string <var>htmlString</var>.</p> + +<h3 id="Exceptions">Exceptions</h3> + +<dl> + <dt><code>SyntaxError</code></dt> + <dd>An attempt was made to set the value of <code>innerHTML</code> using a string which is not properly-formed HTML.</dd> + <dt><code>NoModificationAllowedError</code></dt> + <dd>An attempt was made to insert the HTML into a node whose parent is a {{domxref("Document")}}.</dd> +</dl> + +<h2 id="Usage_notes">Usage notes</h2> + +<p>The <code>innerHTML</code> property can be used to examine the current HTML source of the page, including any changes that have been made since the page was initially loaded.</p> + +<h3 id="Reading_the_HTML_contents_of_an_element">Reading the HTML contents of an element</h3> + +<p>Reading <code>innerHTML</code> causes the user agent to serialize the HTML or XML fragment comprised of the elment's descendants. The resulting string is returned.</p> + +<pre class="brush: js notranslate">let contents = myElement.innerHTML;</pre> + +<p>This lets you look at the HTML markup of the element's content nodes.</p> + +<div class="note"> +<p><strong>Note:</strong> The returned HTML or XML fragment is generated based on the current contents of the element, so the markup and formatting of the returned fragment is likely not to match the original page markup.</p> +</div> + +<div class="note"> +<p><strong>Note:</strong>基於元素的當前內容產生返回的HTML或XML片段，所以返回的片段的標記和格式可能不匹配原始頁面標記。</p> +</div> + +<h3 id="Replacing_the_contents_of_an_element">Replacing the contents of an element</h3> + +<p>Setting the value of <code>innerHTML</code> lets you easily replace the existing contents of an element with new content.</p> + +<p>For example, you can erase the entire contents of a document by clearing the contents of the document's {{domxref("Document.body", "body")}} attribute:</p> + +<pre class="brush: js notranslate">document.body.innerHTML = "";</pre> + +<p>This example fetches the document's current HTML markup and replaces the <code>"<"</code> characters with the HTML entity <code>"&lt;"</code>, thereby essentially converting the HTML into raw text. This is then wrapped in a {{HTMLElement("pre")}} element. Then the value of <code>innerHTML</code> is changed to this new string. As a result, the document contents are replaced with a display of the page's entire source code.</p> + +<pre class="brush: js notranslate">document.documentElement.innerHTML = "<pre>" + + document.documentElement.innerHTML.replace(/</g,"&lt;") + + "</pre>";</pre> + +<h4 id="Operational_details">Operational details</h4> + +<p>What exactly happens when you set value of <code>innerHTML</code>? Doing so causes the user agent to follow these steps:</p> + +<ol> + <li>The specified value is parsed as HTML or XML (based on the document type), resulting in a {{domxref("DocumentFragment")}} object representing the new set of DOM nodes for the new elements.</li> + <li>If the element whose contents are being replaced is a {{HTMLElement("template")}} element, then the <code><template></code> element's {{domxref("HTMLTemplateElement.content", "content")}} attribute is replaced with the new <code>DocumentFragment</code> created in step 1.</li> + <li>For all other elements, the element's contents are replaced with the nodes in the new <code>DocumentFragment</code>.</li> +</ol> + +<h3 id="Security_considerations">Security considerations</h3> + +<p>It is not uncommon to see <code>innerHTML</code> used to insert text into a web page. There is potential for this to become an attack vector on a site, creating a potential security risk.</p> + +<pre class="brush: js notranslate">const name = "John"; +// assuming 'el' is an HTML DOM element +el.innerHTML = name; // harmless in this case + +// ... + +name = "<script>alert('I am John in an annoying alert!')</script>"; +el.innerHTML = name; // harmless in this case</pre> + +<p>Although this may look like a {{interwiki("wikipedia", "cross-site scripting")}} attack, the result is harmless. HTML5 specifies that a {{HTMLElement("script")}} tag inserted with <code>innerHTML</code> <a href="https://www.w3.org/TR/2008/WD-html5-20080610/dom.html#innerhtml0">should not execute</a>.</p> + +<p>However, there are ways to execute JavaScript without using {{HTMLElement("script")}} elements, so there is still a security risk whenever you use <code>innerHTML</code> to set strings over which you have no control. For example:</p> + +<pre class="brush: js notranslate">const name = "<img src='x' onerror='alert(1)'>"; +el.innerHTML = name; // shows the alert</pre> + +<p>For that reason, it is recommended that you do not use <code>innerHTML</code> when inserting plain text; instead, use {{domxref("Node.textContent")}}. This doesn't parse the passed content as HTML, but instead inserts it as raw text.</p> + +<div class="warning"> +<p><strong>Warning:</strong> If your project is one that will undergo any form of security review, using <code>innerHTML</code> most likely will result in your code being rejected. For example, <a href="https://wiki.mozilla.org/Add-ons/Reviewers/Guide/Reviewing#Step_2:_Automatic_validation">if you use <code>innerHTML</code></a> in a <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions">browser extension</a> and submit the extension to <a href="https://addons.mozilla.org/">addons.mozilla.org</a>, it will not pass the automated review process.</p> +</div> + +<h2 id="Example">Example</h2> + +<p>This example uses <code>innerHTML</code> to create a mechanism for logging messages into a box on a web page.</p> + +<h3 id="JavaScript">JavaScript</h3> + +<pre class="brush: js notranslate">function log(msg) { + var logElem = document.querySelector(".log"); + + var time = new Date(); + var timeStr = time.toLocaleTimeString(); + logElem.innerHTML += timeStr + ": " + msg + "<br/>"; +} + +log("Logging mouse events inside this container..."); +</pre> + +<p>The <code>log()</code> function creates the log output by getting the current time from a {{jsxref("Date")}} object using {{jsxref("Date.toLocaleTimeString", "toLocaleTimeString()")}}, and building a string with the timestamp and the message text. Then the message is appended to the box with the class <code>"log"</code>.</p> + +<p>We add a second method that logs information about {{domxref("MouseEvent")}} based events (such as {{event("mousedown")}}, {{event("click")}}, and {{event("mouseenter")}}):</p> + +<pre class="brush: js notranslate">function logEvent(event) { + var msg = "Event <strong>" + event.type + "</strong> at <em>" + + event.clientX + ", " + event.clientY + "</em>"; + log(msg); +}</pre> + +<p>Then we use this as the event handler for a number of mouse events on the box that contains our log:</p> + +<pre class="brush: js notranslate">var boxElem = document.querySelector(".box"); + +boxElem.addEventListener("mousedown", logEvent); +boxElem.addEventListener("mouseup", logEvent); +boxElem.addEventListener("click", logEvent); +boxElem.addEventListener("mouseenter", logEvent); +boxElem.addEventListener("mouseleave", logEvent);</pre> + +<h3 id="HTML">HTML</h3> + +<p>The HTML is quite simple for our example.</p> + +<pre class="brush: html notranslate"><div class="box"> + <div><strong>Log:</strong></div> + <div class="log"></div> +</div></pre> + +<p>The {{HTMLElement("div")}} with the class <code>"box"</code> is just a container for layout purposes, presenting the contents with a box around it. The <code><div></code> whose class is <code>"log"</code> is the container for the log text itself.</p> + +<h3 id="CSS">CSS</h3> + +<p>The following CSS styles our example content.</p> + +<pre class="brush: css notranslate">.box { + width: 600px; + height: 300px; + border: 1px solid black; + padding: 2px 4px; + overflow-y: scroll; + overflow-x: auto; +} + +.log { + margin-top: 8px; + font-family: monospace; +}</pre> + +<h3 id="Result">Result</h3> + +<p>The resulting content looks like this. You can see output into the log by moving the mouse in and out of the box, clicking in it, and so forth.</p> + +<p>{{EmbedLiveSample("Example", 640, 350)}}</p> + +<h2 id="Specification">Specification</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('DOM Parsing', '#dom-element-innerhtml', 'Element.innerHTML')}}</td> + <td>{{Spec2('DOM Parsing')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + + + +<p>{{Compat("api.Element.innerHTML")}}</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li>{{domxref("Node.textContent")}} and {{domxref("Node.innerText")}}</li> + <li>{{domxref("Element.insertAdjacentHTML()")}}</li> + <li>Parsing HTML into a DOM tree: {{domxref("DOMParser")}}</li> + <li>Serializing XML or HTML into a DOM tree: {{domxref("XMLSerializer")}}</li> +</ul> diff --git a/files/zh-tw/web/api/element/insertadjacenthtml/index.html b/files/zh-tw/web/api/element/insertadjacenthtml/index.html new file mode 100644 index 0000000000..6b9da0f403 --- /dev/null +++ b/files/zh-tw/web/api/element/insertadjacenthtml/index.html @@ -0,0 +1,135 @@ +--- +title: Element.insertAdjacentHTML() +slug: Web/API/Element/insertAdjacentHTML +translation_of: Web/API/Element/insertAdjacentHTML +--- +<div>{{APIRef("DOM")}}</div> + +<p><code>insertAdjacentHTML()</code> 把傳入的字串解析成 HTML 或 XML，並把該節點插入到 DOM 樹指定的位置。它不會重新解析被使用的元素，因此他不會破壞該元素裡面原有的元素。這避免了序列化的複雜步驟，使得它比直接操作 <code>innerHTML</code> 快上許多。</p> + +<h2 id="Syntax" name="Syntax">Syntax</h2> + +<pre><em>element</em>.insertAdjacentHTML(<em>position</em>, <em>text</em>);</pre> + +<h3 id="Parameters">Parameters</h3> + +<dl> + <dt>position</dt> + <dd>A {{domxref("DOMString")}} representing the position relative to the <code>element</code>; must be one of the following strings: + <ul> + <li><code style="color: red;">'beforebegin'</code>: 在 <code>element</code> 之前。</li> + <li><code style="color: green;">'afterbegin'</code>: 在 <code>element</code> 裡面，第一個子元素之前。</li> + <li><code style="color: blue;">'beforeend'</code>: 在 <code>element</code> 裡面，最後一個子元素之後。</li> + <li><code style="color: magenta;">'afterend'</code>: 在 <code>element</code> 之後。</li> + </ul> + </dd> + <dt>text</dt> + <dd><code>text</code> 是即將被解析並插入到 DOM 樹裡的字串。</dd> +</dl> + +<h3 id="Visualization_of_position_names">Visualization of position names</h3> + +<pre><!-- beforebegin --> +<p> + <!-- afterbegin --> + foo + <!-- beforeend --> +</p> +<!-- afterend --></pre> + +<div class="note"><strong>Note: </strong> <code>beforebegin</code> 和 <code>afterend</code> 只在該節點位於 DOM 樹內、並且有母元素時有效。</div> + +<h2 id="Example" name="Example">Example</h2> + +<pre class="brush: js">// <div id="one">one</div> +var d1 = document.getElementById('one'); +d1.insertAdjacentHTML('afterend', '<div id="two">two</div>'); + +// At this point, the new structure is: +// <div id="one">one</div><div id="two">two</div></pre> + +<h2 id="Specification" name="Specification">Notes</h2> + +<h3 id="Security_Considerations">Security Considerations</h3> + +<p>When inserting HTML into a page by using <code>insertAdjacentHTML</code> be careful not to use user input that hasn't been escaped.</p> + +<p>It is not recommended you use <code>insertAdjacentHTML</code> when inserting plain text; instead, use the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent" title="The Node.textContent property represents the text content of a node and its descendants."><code>Node.textContent</code></a> property or <a href="https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentText" title="The insertAdjacentText() method inserts a given text node at a given position relative to the element it is invoked upon."><code>Element.insertAdjacentText()</code></a> method. This doesn't interpret the passed content as HTML, but instead inserts it as raw text.</p> + +<h2 id="Specification" name="Specification">Specification</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('DOM Parsing', '#widl-Element-insertAdjacentHTML-void-DOMString-position-DOMString-text', 'Element.insertAdjacentHTML()')}}</td> + <td>{{ Spec2('DOM Parsing') }}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="Browser_Compatibility" name="Browser_Compatibility">Browser compatibility</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>1.0</td> + <td>{{ CompatGeckoDesktop("8.0") }}</td> + <td>4.0</td> + <td>7.0</td> + <td>4.0 (527)</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatGeckoMobile("8.0") }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="See_also">See also</h2> + +<ul> + <li>{{domxref("Element.insertAdjacentElement()")}}</li> + <li>{{domxref("Element.insertAdjacentText()")}}</li> + <li>{{domxref("XMLSerializer")}}: Construct a DOM representation of XML text</li> + <li><a class="external" href="https://hacks.mozilla.org/2011/11/insertadjacenthtml-enables-faster-html-snippet-injection/">hacks.mozilla.org guest post</a><span class="external"> by Henri Sivonen including benchmark showing that insertAdjacentHTML can be way faster in some cases.</span></li> +</ul> diff --git a/files/zh-tw/web/api/element/queryselectorall/index.html b/files/zh-tw/web/api/element/queryselectorall/index.html new file mode 100644 index 0000000000..6f777763bf --- /dev/null +++ b/files/zh-tw/web/api/element/queryselectorall/index.html @@ -0,0 +1,140 @@ +--- +title: Element.querySelectorAll() +slug: Web/API/Element/querySelectorAll +translation_of: Web/API/Element/querySelectorAll +--- +<div>{{APIRef("DOM")}}</div> + +<h2 id="Summary" name="Summary">總覽</h2> + +<p>Returns a non-live <a href="/en-US/docs/DOM/NodeList" title="DOM/NodeList"><code>NodeList</code></a> of all elements descended from the element on which it is invoked that matches the specified group of CSS selectors. (The base element itself is not included, even if it matches.)</p> + +<h2 id="Syntax" name="Syntax">表達式</h2> + +<pre class="syntaxbox"><em>elementList</em> = baseElement.querySelectorAll(<em>selectors</em>);</pre> + +<dl> + <dt><code>elementList</code></dt> + <dd>is a non-live node list [<code> NodeList[elements]</code> <code>] </code>of <a href="/en-US/docs/DOM/element" title="DOM/Element">element</a> objects.</dd> + <dt><code>baseElement</code></dt> + <dd>is an <a href="/en-US/docs/DOM/element" title="DOM/element">element</a> object.</dd> + <dt><code>selectors</code></dt> + <dd>is a group of <a href="/en-US/docs/Web/Guide/CSS/Getting_Started/Selectors">selectors</a> to match on or elements of the DOM. </dd> +</dl> + +<h2 id="Example" name="Example">範例</h2> + +<p>下例是從整個網頁的 body 中，取得所有 <code>p</code> 元素：</p> + +<pre class="brush: js">let matches = document.body.querySelectorAll('p'); +</pre> + +<p>This example returns a list of <code>p</code> children elements under a container, whose parent is a <code>div</code> that has the class 'highlighted':</p> + +<pre class="brush:js">let el = document.querySelector('#test'); //return an element with id='test' +let matches = el.querySelectorAll('div.highlighted > p'); // return a NodeList of p wrapped in a div with attribute class "highlighted" +</pre> + +<p>下例是取得所有有 attribute <code>data-src</code> 的 <code>iframe</code> 元素：</p> + +<pre class="brush: js">let matches = el.querySelectorAll('iframe[data-src]'); +</pre> + +<h2 id="Notes" name="Notes">註</h2> + +<p>If the specified “selectors” are not found inside the DOM of the page, the method <code>queryselectorAll</code> returns an empty NodeList as specified below:</p> + +<pre class="brush: js">> let x = document.body.querySelectorAll('.highlighted'); //case: if the class highlighted doesn't exist in any attribute "class" of the DOM the result is +> [] //empty NodeList</pre> + +<p><code>querySelectorAll()</code> was introduced in the WebApps API.</p> + +<p>The string argument pass to <code>querySelectorAll</code> must follow the CSS syntax. See {{domxref("document.querySelector")}} for a concrete example.</p> + +<p>We could access a single item inside the NodeList in the following way:</p> + +<pre class="brush: js">let x = document.body.querySelectorAll('.highlighted'); +x.length; //return the size of x +x[i_item]; //where i_item has a value between 0 and x.length-1. The operator "[]" return as in an array the element at index "i_item" +</pre> + +<p>We could iterate inside a NodeList with the construct <code>for(....) {...} </code>as in the following code:</p> + +<pre class="brush: js"> let x = document.body.querySelectorAll('.highlighted'); + let index = 0; + for( index=0; index < x.length; index++ ) { + console.log(x[index]); + }</pre> + +<p>So in the above way, it is possible to manage and modify the behaviour of the page.</p> + +<h2 id="Quirks">Quirks</h2> + +<p><code>querySelectorAll()</code> behaves differently than most common JavaScript DOM libraries, which might lead to unexpected results:</p> + +<pre class="brush: html"><div class="outer"> + <div class="select"> + <div class="inner"> + </div> + </div> +</div></pre> + +<pre class="brush: js">let select = document.querySelector('.select'); +let inner = select.querySelectorAll('.outer .inner'); +inner.length; // 1, not 0! +</pre> + +<p>In this example, when selecting <code>.outer .inner</code> in the context of <code>.select</code>, .<code>inner</code> is still found, even though <code>.outer</code> is not a descendant of the baseElement (<code>.select</code>).<br> + <code>querySelectorAll() </code>only verifies that the last element in the selector is within the baseElement.</p> + +<p>The <code><a href="/en-US/docs/Web/CSS/:scope">:scope</a></code> pseudo-class restores the expected behavior, only matching selectors on descendants of the baseElement:</p> + +<pre class="brush: js">let select = document.querySelector('.select'); +let inner = select.querySelectorAll(':scope .outer .inner'); +inner.length; // 0 +</pre> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">評論</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{SpecName('DOM4','#dom-parentnode-queryselectorallselectors','querySelectorAll')}}</td> + <td>{{Spec2('DOM4')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('Selectors API Level 2','#queryselectorall','querySelectorAll')}}</td> + <td>{{Spec2('Selectors API Level 2')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('Selectors API Level 1','#queryselectorall','querySelectorAll')}}</td> + <td>{{Spec2('Selectors API Level 1')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + + + +<div>{{Compat("api.Element.querySelectorAll")}}</div> + +<p>[1] Supported in Opera 15+ by enabling the "<strong>Enable <style scoped></strong>" or "<strong>Enable experimental Web Platform features</strong>" flag in <code>chrome://flags</code>.</p> + +<h2 id="See_also" name="See_also">參見</h2> + +<ul> + <li><a href="/en-US/docs/DOM/Document.querySelectorAll" title="DOM/document.querySelectorAll"><code>document.querySelectorAll</code></a></li> + <li><a href="/en-US/docs/DOM/Document.querySelector" title="DOM/document.querySelector"><code>document.querySelector</code></a></li> + <li><a href="/en-US/docs/Code_snippets/QuerySelector" title="Code_snippets/QuerySelector">Code snippets for <code>querySelector</code></a></li> +</ul> diff --git a/files/zh-tw/web/api/element/scrollheight/index.html b/files/zh-tw/web/api/element/scrollheight/index.html new file mode 100644 index 0000000000..eabf9987bf --- /dev/null +++ b/files/zh-tw/web/api/element/scrollheight/index.html @@ -0,0 +1,170 @@ +--- +title: Element.scrollHeight +slug: Web/API/Element/scrollHeight +tags: + - API + - Reference +translation_of: Web/API/Element/scrollHeight +--- +<p>{{APIRef("DOM")}}</p> + +<p><strong><code>Element.scrollHeight</code></strong> 是衡量元素包含因為 overflow 而沒顯示在螢幕上的內容高度的唯讀屬性. <code>scrollHeight</code> 的值相等於元素要求 <code>clientHeight</code> 在視域中沒有使用滾動條顯示所有內容的最小高度值 . 這當中只包含 padding, 並不包含 margin.</p> + +<div class="note"> +<p>這個屬性會以四捨五入進位取整數. 如果要使用非整數值, 使用 {{ domxref("Element.getBoundingClientRect()") }}.</p> +</div> + +<h2 id="Syntax_and_values" name="Syntax_and_values">表達式</h2> + +<pre class="eval">var <em>intElemScrollHeight</em> = document.getElementById(<em>id_attribute_value</em>).scrollHeight; +</pre> + +<p><em>intElemScrollHeight</em> 是個儲存了元素 scrollHeight 的正整數變數. scrollHeight是唯讀的屬性.</p> + +<h2 id="Example" name="Example">範例</h2> + +<div id="offsetContainer" style="margin: 40px 50px 50px; background-color: rgb(255, 255, 204); border: 4px dashed black; color: black; position: relative; display: inline-block;"> +<div id="idDiv" style="margin: 24px 29px; border: 24px black solid; padding: 0px 28px; width: 199px; height: 102px; overflow: auto; background-color: white; font-size: 13px!important; font-family: Arial, sans-serif;"> +<p id="PaddingTopLabel" style="text-align: center; font-style: italic; font-weight: bold; font-size: 13px!important; font-family: Arial, sans-serif; margin: 0px;">padding-top</p> + +<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p> + +<p>Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p> + +<p id="PaddingBottomLabel" style="text-align: center; font-style: italic; font-weight: bold; font-size: 13px!important; font-family: Arial, sans-serif; margin: 0px;">padding-bottom</p> +</div> +<strong style="color: blue; font-family: arial,sans-serif; font-size: 13px!important; font-weight: bold; left: -32px; position: absolute; top: 85px;">Left</strong> <strong style="color: blue; font-family: arial,sans-serif; font-size: 13px!important; font-weight: bold; left: 170px; position: absolute; top: -24px;">Top</strong> <strong style="color: blue; font-family: arial,sans-serif; font-size: 13px!important; font-weight: bold; left: 370px; position: absolute; top: 85px;">Right</strong> <strong style="color: blue; font-family: arial,sans-serif; font-size: 13px!important; font-weight: bold; left: 164px; position: absolute; top: 203px;">Bottom</strong> <em>margin-top</em> <em>margin-bottom</em> <em>border-top</em> <em>border-bottom</em></div> + +<p><img alt="Image:scrollHeight.png" class="internal" src="/@api/deki/files/840/=ScrollHeight.png"></p> + +<h2 id="問題與解決方法">問題與解決方法</h2> + +<h3 id="了解元素是否被滾輪完全滾過">了解元素是否被滾輪完全滾過</h3> + +<p>下面的等式代表<code>如果元素被完全滾過將會</code>回傳 <code>true </code>, 否則回傳 <code>false</code>.</p> + +<pre class="syntaxbox">element.scrollHeight - element.scrollTop === element.clientHeight</pre> + +<h2 id="scrollHeight_Demo" name="scrollHeight_Demo">scrollHeight 範例</h2> + +<p>藉由 <code><a href="/en-US/docs/DOM/element.onscroll" title="en-US/docs/DOM/element.onscroll">onscroll</a></code> 事件, 這個等式對於決定使用者是否已經讀完文字內容是很有用 (參見 <code><a href="/en-US/docs/DOM/element.scrollTop" title="en-US/docs/DOM/element.scrollTop">element.scrollTop</a></code>, <code><a href="/en-US/docs/DOM/element.clientHeight" title="en-US/docs/DOM/element.clientHeight">element.clientHeight</a></code> 屬性). 範例:</p> + +<h3 id="HTML">HTML</h3> + +<pre class="brush: html"><form name="registration"> + <p> + <textarea id="rules">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum at laoreet magna. +Aliquam erat volutpat. Praesent molestie, dolor ut eleifend aliquam, mi ligula ultrices sapien, quis cursus +neque dui nec risus. Duis tincidunt lobortis purus eu aliquet. Quisque in dignissim magna. Aenean ac lorem at +velit ultrices consequat. Nulla luctus nisi ut libero cursus ultrices. Pellentesque nec dignissim enim. Phasellus +ut quam lacus, sed ultricies diam. Vestibulum convallis rutrum dolor, sit amet egestas velit scelerisque id. +Proin non dignissim nisl. Sed mi odio, ullamcorper eget mattis id, malesuada vitae libero. Integer dolor lorem, +mattis sed dapibus a, faucibus id metus. Duis iaculis dictum pulvinar. In nisi nibh, dapibus ac blandit at, porta +at arcu. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Praesent +dictum ipsum aliquet erat eleifend sit amet sollicitudin felis tempus. Aliquam congue cursus venenatis. Maecenas +luctus pellentesque placerat. Mauris nisl odio, condimentum sed fringilla a, consectetur id ligula. Praesent sem +sem, aliquet non faucibus vitae, iaculis nec elit. Nullam volutpat, lectus et blandit bibendum, nulla lorem congue +turpis, ac pretium tortor sem ut nibh. Donec vel mi in ligula hendrerit sagittis. Donec faucibus viverra fermentum. +Fusce in arcu arcu. Nullam at dignissim massa. Cras nibh est, pretium sit amet faucibus eget, sollicitudin in +ligula. Vivamus vitae urna mauris, eget euismod nunc. Aenean semper gravida enim non feugiat. In hac habitasse +platea dictumst. Cras eleifend nisl volutpat ante condimentum convallis. Donec varius dolor malesuada erat +consequat congue. Donec eu lacus ut sapien venenatis tincidunt. Quisque sit amet tellus et enim bibendum varius et +a orci. Donec aliquet volutpat scelerisque. Proin et tortor dolor. Ut aliquet, dolor a mattis sodales, odio diam +pulvinar sem, egestas pretium magna eros vitae felis. Nam vitae magna lectus, et ornare elit. Morbi feugiat, ipsum +ac mattis congue, quam neque mollis tortor, nec mollis nisl dolor a tortor. Maecenas varius est sit amet elit +interdum quis placerat metus posuere. Duis malesuada justo a diam vestibulum vel aliquam nisi ornare. Integer +laoreet nisi a odio ornare non congue turpis eleifend. Cum sociis natoque penatibus et magnis dis parturient montes, +nascetur ridiculus mus. Cras vulputate libero sed arcu iaculis nec lobortis orci fermentum. + </textarea> + </p> + <p> + <input type="checkbox" name="accept" id="agree" /> + <label for="agree">I agree</label> + <input type="submit" id="nextstep" value="Next" /> + </p> +</form></pre> + +<h3 id="CSS">CSS</h3> + +<pre class="brush: css">#notice { + display: inline-block; + margin-bottom: 12px; + border-radius: 5px; + width: 600px; + padding: 5px; + border: 2px #7FDF55 solid; +} + +#rules { + width: 600px; + height: 130px; + padding: 5px; + border: #2A9F00 solid 2px; + border-radius: 5px; +}</pre> + +<h3 id="JavaScript">JavaScript</h3> + +<pre class="brush: js">function checkReading () { + if (checkReading.read) { + return; + } + checkReading.read = this.scrollHeight - this.scrollTop === this.clientHeight; + document.registration.accept.disabled = document.getElementById("nextstep").disabled = !checkReading.read; + checkReading.noticeBox.innerHTML = checkReading.read ? "Thank you." : "Please, scroll and read the following text."; +} + +onload = function () { + var oToBeRead = document.getElementById("rules"); + checkReading.noticeBox = document.createElement("span"); + document.registration.accept.checked = false; + checkReading.noticeBox.id = "notice"; + oToBeRead.parentNode.insertBefore(checkReading.noticeBox, oToBeRead); + oToBeRead.parentNode.insertBefore(document.createElement("br"), oToBeRead); + oToBeRead.onscroll = checkReading; + checkReading.call(oToBeRead); +}</pre> + +<p>{{ EmbedLiveSample('scrollHeight_Demo', '640', '400') }}</p> + +<h2 id="Specification" name="Specification">規範</h2> + +<p><code>scrollHeight</code> 是 MSIE's <abbr title="Dynamic HyperText Markup Language">DHTML</abbr> 物件模型的一部份. <code>scrollHeight</code> 紀錄在下列的規範: {{SpecName("CSSOM View")}}.</p> + +<h2 id="Supported" name="Supported">瀏覽器相容性</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th>瀏覽器</th> + <th>最低版本</th> + </tr> + <tr> + <td>Internet Explorer</td> + <td><strong>8.0</strong></td> + </tr> + <tr> + <td>Firefox (Gecko)</td> + <td><strong>3.0</strong> (1.9)</td> + </tr> + <tr> + <td>Opera</td> + <td>?</td> + </tr> + <tr> + <td>Safari | Chrome | WebKit</td> + <td><strong>4.0</strong> | <strong>4.0</strong> | ?</td> + </tr> + </tbody> +</table> + +<p><strong>In FireFox versions earlier than 21:</strong> <span style="line-height: 1.5;">When an element's content does not generate a vertical scrollbar, then its </span><code style="font-size: 14px;">scrollHeight</code><span style="line-height: 1.5;"> property is equal to its </span><code style="font-size: 14px;">clientHeight</code><span style="line-height: 1.5;"> property. This can mean either the content is too short to require a scrollbar or that the element has CSS style overflow value of visible (non-scrollable).</span></p> + +<h2 id="See_Also" name="See_Also">參見</h2> + +<ul> + <li><a href="https://docs.microsoft.com/en-us/previous-versions//hh781509(v=vs.85)">MSDN: Measuring Element Dimension and Location with CSSOM in Windows Internet Explorer 9</a></li> + <li>{{domxref("Element.clientHeight")}}</li> + <li>{{domxref("Element.offsetHeight")}}</li> + <li><a href="/en-US/docs/Determining_the_dimensions_of_elements" title="en/Determining_the_dimensions_of_elements">Determining the dimensions of elements</a></li> +</ul> diff --git a/files/zh-tw/web/api/element/scrolltop/index.html b/files/zh-tw/web/api/element/scrolltop/index.html new file mode 100644 index 0000000000..f4fdfe8e09 --- /dev/null +++ b/files/zh-tw/web/api/element/scrolltop/index.html @@ -0,0 +1,73 @@ +--- +title: Element.scrollTop +slug: Web/API/Element/scrollTop +tags: + - API + - CSSOM View + - Reference +translation_of: Web/API/Element/scrollTop +--- +<p>{{ APIRef("DOM") }}</p> + +<p><code><strong>Element.scrollTop</strong></code> 屬性可以設置和獲取元素被向上捲動的高度(pixels). 元素的 <code>scrollTop</code> 是元素頂端和能被看見的最頂端之間的距離. 當元素並未產生滾動條, 那麼 <code>scrollTop</code> 的值預設為 <code>0</code>.</p> + +<h2 id="Syntax_and_values" name="Syntax_and_values">表達式</h2> + +<pre class="eval">// 獲得已經被滾動的距離(pixels) +var <var> intElemScrollTop</var> = someElement.scrollTop; +</pre> + +<p><code><var>intElemScrollTop</var></code> 為 {{domxref("element")}}已經被滾動的距離(pixels ).</p> + +<pre class="eval">// 設置已經被滾動的距離(pixels) +<var>element</var>.scrollTop = <var>intValue</var>; +</pre> + +<p><code>scrollTop</code> 可以被設置為任何和正整數, 注意事項:</p> + +<ul> + <li>如果元素不能滾動, <code>scrollTop</code> 被設置為 <code>0</code>.</li> + <li>如果設置的值小於 <code>0</code>, <code>scrollTop</code> 被設置為 <code>0</code>.</li> + <li>如果設置的值大於內容可以被滾動的距離, <code>scrollTop</code> 被設置為最大值.</li> +</ul> + +<h2 id="Example" name="Example">範例</h2> + +<div id="offsetContainer" style="margin: 40px 50px 50px; background-color: rgb(255, 255, 204); border: 4px dashed black; color: black; position: relative; display: inline-block;"> +<div id="idDiv" style="margin: 24px 29px; border: 24px black solid; padding: 0px 28px; width: 199px; height: 102px; overflow: auto; background-color: white; font-size: 13px!important; font-family: Arial, sans-serif;"> +<p id="PaddingTopLabel" style="text-align: center; font-style: italic; font-weight: bold; font-size: 13px!important; font-family: Arial, sans-serif; margin: 0px;">padding-top</p> + +<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p> + +<p>Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p> + +<p id="PaddingBottomLabel" style="text-align: center; font-style: italic; font-weight: bold; font-size: 13px!important; font-family: Arial, sans-serif; margin: 0px;">padding-bottom</p> +</div> +<strong style="color: blue; font-family: arial,sans-serif; font-size: 13px!important; font-weight: bold; left: -32px; position: absolute; top: 85px;">Left</strong> <strong style="color: blue; font-family: arial,sans-serif; font-size: 13px!important; font-weight: bold; left: 170px; position: absolute; top: -24px;">Top</strong> <strong style="color: blue; font-family: arial,sans-serif; font-size: 13px!important; font-weight: bold; left: 370px; position: absolute; top: 85px;">Right</strong> <strong style="color: blue; font-family: arial,sans-serif; font-size: 13px!important; font-weight: bold; left: 164px; position: absolute; top: 203px;">Bottom</strong> <em>margin-top</em> <em>margin-bottom</em> <em>border-top</em> <em>border-bottom</em></div> + +<p><img alt="Image:scrollTop.png" class="internal" src="/@api/deki/files/842/=ScrollTop.png"></p> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">註</th> + </tr> + <tr> + <td>{{SpecName('CSSOM View', '#dom-element-scrolltop', 'scrollTop')}}</td> + <td>{{Spec2("CSSOM View")}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="參閱">參閱</h2> + +<ul> + <li><a class="external" href="http://dev.w3.org/csswg/cssom-view/#dom-element-scrolltop" title="http://dev.w3.org/csswg/cssom-view/#dom-element-scrolltop">W3C Draft CSSOM View Module</a></li> + <li><a class="external" href="http://msdn.microsoft.com/en-us/library/ms534618(VS.85).aspx" title="http://msdn.microsoft.com/en-us/library/ms534618(VS.85).aspx">MSDN's scrollTop definition</a></li> + <li><a href="http://msdn.microsoft.com/en-us/library/hh781509(v=vs.85).aspx" title="http://msdn.microsoft.com/en-us/library/hh781509(v=vs.85).aspx">MSDN's Measuring Element Dimension and Location</a></li> +</ul> diff --git a/files/zh-tw/web/api/element/touchcancel_event/index.html b/files/zh-tw/web/api/element/touchcancel_event/index.html new file mode 100644 index 0000000000..99fa1c27a2 --- /dev/null +++ b/files/zh-tw/web/api/element/touchcancel_event/index.html @@ -0,0 +1,169 @@ +--- +title: touchcancel +slug: Web/API/Element/touchcancel_event +translation_of: Web/API/Element/touchcancel_event +--- +<p>{{APIRef}}</p> + +<p><code>touchcancel 觸控點發生失效的事件被觸發(例如太多觸控點時)</code></p> + +<h2 id="一般資訊">一般資訊</h2> + +<dl> + <dt style="float: left; text-align: right; width: 120px;">規範</dt> + <dd style="margin: 0 0 0 120px;"><a class="external" href="http://www.w3.org/TR/touch-events/#the-touchcancel-event">Touch Events</a></dd> + <dt style="float: left; text-align: right; width: 120px;">介面</dt> + <dd style="margin: 0 0 0 120px;">TouchEvent</dd> + <dt style="float: left; text-align: right; width: 120px;">起泡事件</dt> + <dd style="margin: 0 0 0 120px;">是</dd> + <dt style="float: left; text-align: right; width: 120px;">可取消</dt> + <dd style="margin: 0 0 0 120px;">否</dd> + <dt style="float: left; text-align: right; width: 120px;">對象</dt> + <dd style="margin: 0 0 0 120px;">Document, Element</dd> + <dt style="float: left; text-align: right; width: 120px;">預設行為</dt> + <dd style="margin: 0 0 0 120px;">無</dd> +</dl> + +<h2 id="屬性">屬性</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Property</th> + <th scope="col">Type</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>target</code> {{readonlyInline}}</td> + <td>EventTarget</td> + <td>The event target (the topmost target in the DOM tree).</td> + </tr> + <tr> + <td><code>type</code> {{readonlyInline}}</td> + <td>DOMString</td> + <td>The type of event.</td> + </tr> + <tr> + <td><code>bubbles</code> {{readonlyInline}}</td> + <td>Boolean</td> + <td>Whether the event normally bubbles or not.</td> + </tr> + <tr> + <td><code>cancelable</code> {{readonlyInline}}</td> + <td>Boolean</td> + <td>Whether the event is cancellable or not.</td> + </tr> + <tr> + <td><code>view</code> {{readonlyInline}}</td> + <td>WindowProxy</td> + <td><a href="/en-US/docs/Web/API/Document/defaultView" title="In browsers, document.defaultView returns the window object associated with a document, or null if none is available."><code>document.defaultView</code></a> (<code>window</code> of the document)</td> + </tr> + <tr> + <td><code>detail</code> {{readonlyInline}}</td> + <td>long (float)</td> + <td>0.</td> + </tr> + <tr> + <td><code>touches</code> {{readonlyInline}}</td> + <td>TouchList</td> + <td>A list of <a href="/en/DOM/Touch"><code>Touch</code></a>es for every point of contact currently touching the surface.</td> + </tr> + <tr> + <td><code>targetTouches</code> {{readonlyInline}}</td> + <td>TouchList</td> + <td>A list of <a href="/en/DOM/Touch"><code>Touch</code></a>es for every point of contact that is touching the surface and started on the element that is the target of the current event.</td> + </tr> + <tr> + <td><code>changedTouches</code> {{readonlyInline}}</td> + <td>TouchList</td> + <td>A list of <a href="/en-US/docs/DOM/Touch"><code>Touch</code></a>es for every point of contact which contributed to the event.<br> + For the touchstart event this must be a list of the touch points that just became active with the current event. For the touchmove event this must be a list of the touch points that have moved since the last event. For the touchend and touchcancel events this must be a list of the touch points that have just been removed from the surface.</td> + </tr> + <tr> + <td><code>ctrlKey</code> {{readonlyInline}}</td> + <td>boolean</td> + <td><code>true</code> if the control key was down when the event was fired. <code>false</code> otherwise.</td> + </tr> + <tr> + <td><code>shiftKey</code> {{readonlyInline}}</td> + <td>boolean</td> + <td><code>true</code> if the shift key was down when the event was fired. <code>false</code> otherwise.</td> + </tr> + <tr> + <td><code>altKey</code> {{readonlyInline}}</td> + <td>boolean</td> + <td><code>true</code> if the alt key was down when the event was fired. <code>false</code> otherwise.</td> + </tr> + <tr> + <td><code>metaKey</code> {{readonlyInline}}</td> + <td>boolean</td> + <td><code>true</code> if the meta key was down when the event was fired. <code>false</code> otherwise.</td> + </tr> + </tbody> +</table> + +<h2 id="範例">範例</h2> + +<p>各種觸控事件的範例：<a href="/en-US/docs/DOM/Touch_events">Touch events</a>。</p> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatChrome("22.0")}}</td> + <td>{{CompatGeckoDesktop("18.0")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</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>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("6.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>11</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="相關事件">相關事件</h2> + +<p>{{ domxref("GlobalEventHandlers.ontouchcancel","ontouchcancel")}}</p> diff --git a/files/zh-tw/web/api/errorevent/index.html b/files/zh-tw/web/api/errorevent/index.html new file mode 100644 index 0000000000..27e406ed7c --- /dev/null +++ b/files/zh-tw/web/api/errorevent/index.html @@ -0,0 +1,148 @@ +--- +title: ErrorEvent +slug: Web/API/ErrorEvent +translation_of: Web/API/ErrorEvent +--- +<p>{{APIRef("HTML DOM")}}</p> + +<p><strong><code>ErrorEvent</code></strong> 介面是用來提供程式碼或是檔案的錯誤訊息的事件。</p> + +<h2 id="Properties">Properties</h2> + +<p><em>此介面繼承了其父 {{domxref("Event")}} 的 properties 。</em></p> + +<dl> + <dt>{{domxref("ErrorEvent.message")}} {{readonlyInline}}</dt> + <dd>一 {{domxref("DOMString")}} 提供具可讀性的關於問題的錯誤訊息。</dd> + <dt>{{domxref("ErrorEvent.filename")}} {{readonlyInline}}</dt> + <dd>一 {{domxref("DOMString")}} ，為發生錯誤的程式碼檔案的檔名。</dd> + <dt>{{domxref("ErrorEvent.lineno")}} {{readonlyInline}}</dt> + <dd>一 <code>整數</code> ，為發生問題的程式的行數。</dd> + <dt>{{domxref("ErrorEvent.colno")}} {{readonlyInline}}</dt> + <dd>一 <code>整數</code> ，為發生問題的程式的欄數。</dd> + <dt>{{domxref("ErrorEvent.error")}} {{readonlyInline}} {{experimental_inline}}</dt> + <dd>一個參與該事件的 JavaScript <code>Object</code> 。</dd> +</dl> + +<h2 id="Constructor">Constructor</h2> + +<dl> + <dt>{{domxref("ErrorEvent.ErrorEvent", "ErrorEvent()")}}</dt> + <dd>建立一 <code>ErrorEvent</code> 事件，其包含提供的參數。</dd> +</dl> + +<h2 id="Methods">Methods</h2> + +<p><em>此介面繼承了其父 {{domxref("Event")}} 的 methods。</em></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', 'webappapis.html#the-errorevent-interface', 'ErrorEvent') }}</td> + <td>{{ Spec2('HTML WHATWG') }}</td> + <td>追加 <code>error</code> propriety 以及 constructor 的第5個the 5th 參數。</td> + </tr> + <tr> + <td>{{ SpecName('HTML5 W3C', 'webappapis.html#the-errorevent-interface', 'ErrorEvent') }}</td> + <td>{{ Spec2('HTML5 W3C') }}</td> + <td>初始定義。</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器支援度比較">瀏覽器支援度比較</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>colno</code> property and 4th argument to constructor</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>error</code> property and 5th argument to constructor</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</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>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>colno</code> property and 4th argument to constructor</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>error</code> property and 5th argument to constructor</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="延伸閱讀">延伸閱讀</h2> + +<ul> + <li><a href="/en-US/docs/Web/Guide/Performance/Using_web_workers" title="/en-US/docs/Web/Guide/Performance/Using_web_workers">Using web workers</a>, most likely objects to raise such an event</li> +</ul> diff --git a/files/zh-tw/web/api/event/bubbles/index.html b/files/zh-tw/web/api/event/bubbles/index.html new file mode 100644 index 0000000000..4a495fc672 --- /dev/null +++ b/files/zh-tw/web/api/event/bubbles/index.html @@ -0,0 +1,63 @@ +--- +title: Event.bubbles +slug: Web/API/Event/bubbles +translation_of: Web/API/Event/bubbles +--- +<p>{{ ApiRef("DOM") }}</p> + +<h3 id="Summary" name="Summary">概述</h3> + +<p>表示事件是否會向上冒泡傳遞。</p> + +<h3 id="語法">語法</h3> + +<pre class="eval"><em>var bool</em> = event.bubbles; +</pre> + +<p>回傳一個布林值，若事件會向上冒泡傳遞則回傳 <code>true</code>。</p> + +<h3 id="Notes" name="Notes">備註</h3> + +<p>Only certain events can bubble. Events that do bubble have this property set to <code>true</code>. You can use this property to check if an event is allowed to bubble or not.</p> + +<h3 id="Example" name="Example">範例</h3> + +<pre class="brush: js"> function goInput(e) { + // checks bubbles and + if (!e.bubbles) { + // passes event along if it's not + passItOn(e); + } + // already bubbling + doOutput(e) +} +</pre> + +<h2 id="Specifications" name="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('DOM WHATWG', '#dom-event-bubbles', 'Event.bubbles')}}</td> + <td>{{ Spec2('DOM WHATWG') }}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM4', '#dom-event-bubbles', 'Event.bubbles')}}</td> + <td>{{ Spec2('DOM4') }}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM2 Events', '#Events-Event-canBubble', 'Event.bubbles')}}</td> + <td>{{ Spec2('DOM2 Events') }}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> diff --git a/files/zh-tw/web/api/event/comparison_of_event_targets/index.html b/files/zh-tw/web/api/event/comparison_of_event_targets/index.html new file mode 100644 index 0000000000..211463b1a7 --- /dev/null +++ b/files/zh-tw/web/api/event/comparison_of_event_targets/index.html @@ -0,0 +1,164 @@ +--- +title: Comparison of Event Targets +slug: Web/API/Event/Comparison_of_Event_Targets +translation_of: Web/API/Event/Comparison_of_Event_Targets +--- +<p>{{ ApiRef() }}</p> + +<h3 id="Event_targets" name="Event_targets">Event targets</h3> + +<p>It's easy to get confused about which target to examine when writing an event handler. This article should clarify the use of the target properties.</p> + +<p>There are 5 targets to consider:</p> + +<table class="standard-table"> + <tbody> + <tr> + <th>Property</th> + <th>Defined in</th> + <th>Purpose</th> + </tr> + <tr> + <td><a href="/en/DOM/event.target" title="en/DOM/event.target">event.target</a></td> + <td><a class="external" href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-interface">DOM Event Interface</a></td> + <td> + <p>The DOM element on the lefthand side of the call that triggered this event, eg:</p> + + <pre class="eval"> +<em>element</em>.dispatchEvent(<em>event</em>) +</pre> + </td> + </tr> + <tr> + <td><a href="/en/DOM/event.currentTarget" title="en/DOM/event.currentTarget">event.currentTarget</a></td> + <td><a class="external" href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-interface">DOM Event Interface</a></td> + <td>The <a class="external" href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-EventTarget"><code>EventTarget</code></a> whose <a class="external" href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-EventListener"><code>EventListeners</code></a> are currently being processed. As the event capturing and bubbling occurs this value changes.</td> + </tr> + <tr> + <td><a href="/en/DOM/event.relatedTarget" title="en/DOM/event.relatedTarget">event.relatedTarget</a></td> + <td><a class="external" href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-MouseEvent">DOM MouseEvent Interface</a></td> + <td>Identifies a secondary target for the event.</td> + </tr> + <tr> + <td><a href="/en/DOM/event.explicitOriginalTarget" title="en/DOM/event.explicitOriginalTarget">event.explicitOriginalTarget</a></td> + <td>{{ Source("/dom/public/idl/events/nsIDOMNSEvent.idl", "nsIDOMNSEvent.idl") }}</td> + <td>{{ Non-standard_inline() }} If the event was retargeted for some reason other than an anonymous boundary crossing, this will be set to the target before the retargeting occurs. For example, mouse events are retargeted to their parent node when they happen over text nodes ({{ Bug("185889") }}), and in that case <code>.target</code> will show the parent and <code>.explicitOriginalTarget</code> will show the text node.<br> + Unlike <code>.originalTarget</code>, <code>.explicitOriginalTarget</code> will never contain anonymous content.</td> + </tr> + <tr> + <td><a href="/en/DOM/event.originalTarget" title="en/DOM/event.originalTarget">event.originalTarget</a></td> + <td>{{ Source("/dom/public/idl/events/nsIDOMNSEvent.idl", "nsIDOMNSEvent.idl") }}</td> + <td>{{ Non-standard_inline() }} The original target of the event, before any retargetings. See <a href="/en-US/docs/XBL/XBL_1.0_Reference/Anonymous_Content#Event_Flow_and_Targeting" title="en/XBL/XBL_1.0_Reference/Anonymous_Content#Event_Flow_and_Targeting">Anonymous Content#Event_Flow_and_Targeting</a> for details.</td> + </tr> + </tbody> +</table> + +<h3 id="Use_of_explicitOriginalTarget_and_originalTarget" name="Use_of_explicitOriginalTarget_and_originalTarget">Use of <code>explicitOriginalTarget</code> and <code>originalTarget</code></h3> + +<p>TODO: Only available in a Mozilla-based browser? TODO: Only suitable for extension-developers?</p> + +<h3 id="Examples" name="Examples">範例</h3> + +<pre><!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <title>Comparison of Event Targets</title> + <style> + table { + border-collapse: collapse; + height: 150px; + width: 100%; + } + td { + border: 1px solid #ccc; + font-weight: bold; + padding: 5px; + min-height: 30px; + } + .standard { + background-color: #99ff99; + } + .non-standard { + background-color: #902D37; + } + </style> +</head> +<body> + <table> + <thead> + <tr> + <td class="standard">Original target dispatching the event <small>event.target</small></td> + <td class="standard">Target who's event listener is being processed <small>event.currentTarget</small></td> + <td class="standard">Identify other element (if any) involved in the event <small>event.relatedTarget</small></td> + <td class="non-standard">If there was a retargetting of the event for some reason <small> event.explicitOriginalTarget</small> contains the target before retargetting (never contains anonymous targets)</td> + <td class="non-standard">If there was a retargetting of the event for some reason <small> event.originalTarget</small> contains the target before retargetting (may contain anonymous targets)</td> + </tr> + </thead> + <tr> + <td id="target"></td> + <td id="currentTarget"></td> + <td id="relatedTarget"></td> + <td id="explicitOriginalTarget"></td> + <td id="originalTarget"></td> + </tr> +</table> +<p>Clicking on the text will show the difference between explicitOriginalTarget, originalTarget and target</p> +<script> + function handleClicks(e) { + document.getElementById('target').innerHTML = e.target; + document.getElementById('currentTarget').innerHTML = e.currentTarget; + document.getElementById('relatedTarget').innerHTML = e.relatedTarget; + document.getElementById('explicitOriginalTarget').innerHTML = e.explicitOriginalTarget; + document.getElementById('originalTarget').innerHTML = e.originalTarget; + } + + function handleMouseover(e) { + document.getElementById('target').innerHTML = e.target; + document.getElementById('relatedTarget').innerHTML = e.relatedTarget; + } + + document.addEventListener('click', handleClicks, false); + document.addEventListener('mouseover', handleMouseover, false); +</script> +</body> +</html></pre> + +<h3 id="Use_of_target_and_relatedTarget" name="Use_of_target_and_relatedTarget">Use of <code>target</code> and <code>relatedTarget</code></h3> + +<p>The <code>relatedTarget</code> property for the <code>mouseover</code> event holds the node that the mouse was previously over. For the <code>mouseout</code> event, it holds the node that the mouse moved to.</p> + +<table class="standard-table"> + <tbody> + <tr> + <th>Event type</th> + <th><a href="/en/DOM/event.target" title="en/DOM/event.target">event.target</a></th> + <th><a href="/en/DOM/event.relatedTarget" title="en/DOM/event.relatedTarget">event.relatedTarget</a></th> + </tr> + <tr> + <td><code>mouseover</code></td> + <td>the EventTarget which the pointing device entered</td> + <td>the EventTarget which the pointing device exited</td> + </tr> + <tr> + <td><code>mouseout</code></td> + <td>the EventTarget which the pointing device exited</td> + <td>the EventTarget which the pointing device entered</td> + </tr> + </tbody> +</table> + +<p>TODO: Also needs descriptions about <code>dragenter</code> and <code>dragexit</code> events.</p> + +<h4 id="Example" name="Example">範例</h4> + +<pre class="eval"><hbox id="outer"> + <hbox id="inner" + onmouseover="dump('mouseover ' + event.relatedTarget.id + ' > ' + event.target.id + '\n');" + onmouseout="dump('mouseout ' + event.target.id + ' > ' + event.relatedTarget.id + '\n');" + style="margin: 100px; border: 10px solid black; width: 100px; height: 100px;" /> +</hbox> +</pre> + +<p> </p> diff --git a/files/zh-tw/web/api/event/createevent/index.html b/files/zh-tw/web/api/event/createevent/index.html new file mode 100644 index 0000000000..fd60d1089d --- /dev/null +++ b/files/zh-tw/web/api/event/createevent/index.html @@ -0,0 +1,29 @@ +--- +title: Event.createEvent() +slug: Web/API/Event/createEvent +translation_of: Web/API/Document/createEvent +--- +<p>{{APIRef("DOM")}}</p> + +<p>建立一個新的事件，該事件必須先以其 <code>init()</code> method 初始化才行。</p> + +<h3 id="語法">語法</h3> + +<pre><code>document.createEvent(type) </code></pre> + +<dl> + <dt><code>type</code></dt> + <dd>一個 string 。表示所建立的事件名稱。</dd> +</dl> + +<p>這個 method 會回傳一個新的 DOM {{ domxref("Event") }} object ，其事件類型為傳入的 type 。該事件必須先初始化才能使用。</p> + +<h3 id="範例">範例</h3> + +<pre class="brush: js">var newEvent = document.createEvent("UIEvents");</pre> + +<h3 id="規格定義">規格定義</h3> + +<ul> + <li><a class="external" href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-document" title="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-document">DOM Level 2 Events</a></li> +</ul> diff --git a/files/zh-tw/web/api/event/currenttarget/index.html b/files/zh-tw/web/api/event/currenttarget/index.html new file mode 100644 index 0000000000..2be9aeb4e7 --- /dev/null +++ b/files/zh-tw/web/api/event/currenttarget/index.html @@ -0,0 +1,70 @@ +--- +title: Event.currentTarget +slug: Web/API/Event/currentTarget +translation_of: Web/API/Event/currentTarget +--- +<div>{{APIRef("DOM")}}</div> + +<p>{{domxref("Event")}} 介面的唯讀屬性 <code><strong>currentTarget</strong></code> 會標明事件指向（current target）、還有該事件所遍歷的 DOM。屬性總會指向當時處理該事件的事件監聽器所註冊的 DOM 物件，而 {{domxref("event.target")}} 屬性則是永遠指向觸發事件的 DOM 物件。</p> + +<h2 id="範例">範例</h2> + +<p><code>event.currentTarget</code> 在把相同的事件監聽器，附加到多個元素時，會出現很有趣的事情：</p> + +<pre class="brush: js">function hide(e){ + e.currentTarget.style.visibility = "hidden"; + // 在這個函式用於事件監聽器時： this === e.currentTarget +} + +var ps = document.getElementsByTagName('p'); + +for(var i = 0; i < ps.length; i++){ + ps[i].addEventListener('click', hide, false); +} + +// 單擊四周的話 p 元素就會消失 +</pre> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th>規範</th> + <th>狀態</th> + <th>註解</th> + </tr> + <tr> + <td>{{SpecName("DOM WHATWG", "#dom-event-currenttarget", "Event.currentTarget")}}</td> + <td>{{Spec2("DOM WHATWG")}}</td> + <td></td> + </tr> + <tr> + <td>{{SpecName("DOM4", "#dom-event-currenttarget", "Event.currentTarget")}}</td> + <td>{{Spec2("DOM4")}}</td> + <td></td> + </tr> + <tr> + <td>{{SpecName("DOM3 Events", "#dfn-current-event-target", "current event target")}}</td> + <td>{{Spec2("DOM3 Events")}}</td> + <td></td> + </tr> + <tr> + <td>{{SpecName("DOM2 Events", "#Events-Event-currentTarget", "Event.currentTarget")}}</td> + <td>{{Spec2("DOM2 Events")}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + + + +<p>{{Compat("api.Event.currentTarget")}}</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/zh-TW/docs/Web/API/Event/Comparison_of_Event_Targets">事件指向的比較</a></li> +</ul> diff --git a/files/zh-tw/web/api/event/defaultprevented/index.html b/files/zh-tw/web/api/event/defaultprevented/index.html new file mode 100644 index 0000000000..d0814682a8 --- /dev/null +++ b/files/zh-tw/web/api/event/defaultprevented/index.html @@ -0,0 +1,100 @@ +--- +title: Event.defaultPrevented +slug: Web/API/Event/defaultPrevented +translation_of: Web/API/Event/defaultPrevented +--- +<div>{{ APIRef("DOM") }}</div> + +<h2 id="概述">概述</h2> + +<p>回傳一個布林值，表示事件的預設行為是否被取消，也就是事件物件是否曾執行 {{domxref("event.preventDefault()", "preventDefault()")}} 方法。</p> + +<div class="note"><strong>註：</strong>You should use this instead of the non-standard, deprecated<code> getPreventDefault()</code> method (see {{ bug(691151) }}).</div> + +<h2 id="語法">語法</h2> + +<pre class="eval">bool = event.defaultPrevented </pre> + +<h2 id="範例">範例</h2> + +<pre> if (e.defaultPrevented) { + /* the default was prevented */ + } +</pre> + +<h2 id="規範">規範</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('DOM WHATWG', '#dom-event-defaultprevented', 'Event.defaultPrevented()')}}</td> + <td>{{ Spec2('DOM WHATWG') }}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM4', '#dom-event-defaultprevented', 'Event.defaultPrevented')}}</td> + <td>{{Spec2('DOM4')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性"><span style="font-size: 1.71428571428571rem; letter-spacing: -0.021em; line-height: 1;">瀏覽器相容性</span></h2> + +<p>{{ CompatibilityTable() }}</p> + +<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(18) }}</td> + <td>{{ CompatGeckoDesktop("6.0") }}</td> + <td>{{ CompatIE(9.0) }}</td> + <td>{{ CompatOpera(11.0) }}</td> + <td>{{ CompatSafari("5.0") }}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatGeckoMobile("6.0") }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatSafari(5.0) }}</td> + </tr> + </tbody> +</table> +</div> + +<ul> +</ul> diff --git a/files/zh-tw/web/api/event/event/index.html b/files/zh-tw/web/api/event/event/index.html new file mode 100644 index 0000000000..bbbd74c5b2 --- /dev/null +++ b/files/zh-tw/web/api/event/event/index.html @@ -0,0 +1,87 @@ +--- +title: Event() +slug: Web/API/Event/Event +translation_of: Web/API/Event/Event +--- +<p>{{APIRef("DOM")}}</p> + +<p><code><strong>Event()</strong></code> constructor 能用來建立一個 {{domxref("Event", "事件")}} 。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><em>event</em> = new Event(<em>typeArg</em>, <em>eventInit</em>);</pre> + +<h3 id="參數">參數</h3> + +<dl> + <dt><em>typeArg</em></dt> + <dd>為一 {{domxref("DOMString")}} ，用來表示事件名稱。</dd> + <dt><em>eventInit</em>{{optional_inline}}</dt> + <dd>一個 <code>EventInit</code> object，包含以下欄位 + <table class="standard-table"> + <thead> + <tr> + <th>參數</th> + <th>可選</th> + <th>默認值</th> + <th>類型</th> + <th>說明</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>"bubbles"</code></td> + <td>●</td> + <td><code>false</code></td> + <td><code>{{jsxref("Boolean")}}</code></td> + <td>表示該事件是否懸浮（bubble up）。</td> + </tr> + <tr> + <td><code>"cancelable"</code></td> + <td>●</td> + <td><code>false</code></td> + <td>{{jsxref("Boolean")}}</td> + <td>表示該事件是否已取消（canale）。</td> + </tr> + </tbody> + </table> + </dd> +</dl> + +<h2 id="範例">範例</h2> + +<pre class="brush: js">// 建立一個 bubbles up 、並未被取消的事件 “look” 。 +var ev = new Event("look", {"bubbles":true, "cancelable":false}); +document.dispatchEvent(ev); +</pre> + +<h2 id="規格">規格</h2> + +<table class="standard-table" style="height: 49px; width: 1000px;"> + <thead> + <tr> + <th scope="col">Specification</th> + <th scope="col">Status</th> + <th scope="col">Comment</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{SpecName('DOM WHATWG','#interface-event','Event()')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + + + +<p>{{Compat("api.Event.Event")}}</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("Event")}}</li> +</ul> diff --git a/files/zh-tw/web/api/event/eventphase/index.html b/files/zh-tw/web/api/event/eventphase/index.html new file mode 100644 index 0000000000..e146e7b230 --- /dev/null +++ b/files/zh-tw/web/api/event/eventphase/index.html @@ -0,0 +1,179 @@ +--- +title: Event.eventPhase +slug: Web/API/Event/eventPhase +translation_of: Web/API/Event/eventPhase +--- +<p>{{ApiRef("DOM")}}</p> + +<p>表示事件物件目前於事件流（Event Flow）中傳遞的進度為哪一個階段。</p> + +<h2 id="語法">語法</h2> + +<pre class="brush: js"><em>var phase</em> = event.eventPhase; +</pre> + +<p>回傳一個整數值以代表目前事件於事件流中的傳遞階段，可能的值將於{{anch("事件傳遞階段常數")}}說明。</p> + +<h2 id="常數">常數</h2> + +<h3 id="事件傳遞階段常數">事件傳遞階段常數</h3> + +<p>These values describe which phase the event flow is currently being evaluated.</p> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">常數</th> + <th scope="col">值</th> + <th scope="col">說明</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{domxref("Event.NONE")}} {{readonlyinline}}</td> + <td>0</td> + <td>No event is being processed at this time.</td> + </tr> + <tr> + <td>{{domxref("Event.CAPTURING_PHASE")}} {{readonlyinline}}</td> + <td>1</td> + <td>The event is being propagated through the target's ancestor objects. This process starts with the {{domxref("Window")}}, then {{domxref("Document")}}, then the {{domxref("HTMLHtmlElement")}}, and so on through the elements until the target's parent is reached. {{domxref("EventListener", "Event listeners", "", 1)}} registered for capture mode when {{domxref("EventTarget.addEventListener()")}} was called are triggered during this phase.</td> + </tr> + <tr> + <td>{{domxref("Event.AT_TARGET")}} {{readonlyinline}}</td> + <td>2</td> + <td>The event has arrived at {{domxref("EventTarget", "the event's target", "", 1)}}. Event listeners registered for this phase are called at this time. If {{domxref("Event.bubbles")}} is false, processing the event is finished after this phase is complete.</td> + </tr> + <tr> + <td>{{domxref("Event.BUBBLING_PHASE")}} {{readonlyinline}}</td> + <td>3</td> + <td>The event is propagating back up through the target's ancestors in reverse order, starting with the parent, and eventually reaching the containing {{domxref("Window")}}. This is known as bubbling, and occurs only if {{domxref("Event.bubbles")}} is <code>true</code>. {{domxref("EventListener", "Event listeners", "", 1)}} registered for this phase are triggered during this process.</td> + </tr> + </tbody> +</table> + +<p>For more details, see <a class="external" href="http://www.w3.org/TR/DOM-Level-3-Events/#event-flow">section 3.1, Event dispatch and DOM event flow</a>, of the DOM Level 3 Events specification.</p> + +<h2 id="Example" name="Example">範例</h2> + +<h3 id="HTML_Content">HTML Content</h3> + +<pre class="brush: html"><h4>Event Propagation Chain</h4> +<ul> + <li>Click 'd1'</li> + <li>Analyse event propagation chain</li> + <li>Click next div and repeat the experience</li> + <li>Change Capturing mode</li> + <li>Repeat the experience</li> +</ul> +<input type="checkbox" id="chCapture" /> +<label for="chCapture">Use Capturing</label> + <div id="d1">d1 + <div id="d2">d2 + <div id="d3">d3 + <div id="d4">d4</div> + </div> + </div> + </div> + <div id="divInfo"></div> +</pre> + +<h3 id="CSS_Content">CSS Content</h3> + +<pre class="brush: css">div { + margin: 20px; + padding: 4px; + border: thin black solid; +} + +#divInfo { + margin: 18px; + padding: 8px; + background-color:white; + font-size:80%; +}</pre> + +<h3 id="JavaScript_Content">JavaScript Content</h3> + +<pre class="brush: js">var clear = false, divInfo = null, divs = null, useCapture = false; +window.onload = function () { + divInfo = document.getElementById("divInfo"); + divs = document.getElementsByTagName('div'); + chCapture = document.getElementById("chCapture"); + chCapture.onclick = function () { + RemoveListeners(); + AddListeners(); + } + Clear(); + AddListeners(); +} + +function RemoveListeners() { + for (var i = 0; i < divs.length; i++) { + var d = divs[i]; + if (d.id != "divInfo") { + d.removeEventListener("click", OnDivClick, true); + d.removeEventListener("click", OnDivClick, false); + } + } +} + +function AddListeners() { + for (var i = 0; i < divs.length; i++) { + var d = divs[i]; + if (d.id != "divInfo") { + d.addEventListener("click", OnDivClick, false); + if (chCapture.checked) + d.addEventListener("click", OnDivClick, true); + d.onmousemove = function () { clear = true; }; + } + } +} + +function OnDivClick(e) { + if (clear) { + Clear(); clear = false; + } + if (e.eventPhase == 2) + e.currentTarget.style.backgroundColor = 'red'; + var level = e.eventPhase == 0 ? "none" : e.eventPhase == 1 ? "capturing" : e.eventPhase == 2 ? "target" : e.eventPhase == 3 ? "bubbling" : "error"; + divInfo.innerHTML += e.currentTarget.id + "; eventPhase: " + level + "<br/>"; +} + +function Clear() { + for (var i = 0; i < divs.length; i++) { + if (divs[i].id != "divInfo") + divs[i].style.backgroundColor = (i & 1) ? "#f6eedb" : "#cceeff"; + } + divInfo.innerHTML = ''; +} +</pre> + +<p>{{ EmbedLiveSample('Example', '', '700', '', 'Web/API/Event/eventPhase') }}</p> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th>Specification</th> + <th>Status</th> + <th>Comment</th> + </tr> + <tr> + <td>{{SpecName("DOM WHATWG", "#dom-event-eventphase", "Event.eventPhase")}}</td> + <td>{{Spec2("DOM WHATWG")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("DOM4", "#dom-event-eventphase", "Event.eventPhase")}}</td> + <td>{{Spec2("DOM4")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("DOM2 Events", "#Events-Event-eventPhase", "Event.eventPhase")}}</td> + <td>{{Spec2("DOM2 Events")}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> diff --git a/files/zh-tw/web/api/event/index.html b/files/zh-tw/web/api/event/index.html new file mode 100644 index 0000000000..4213c20080 --- /dev/null +++ b/files/zh-tw/web/api/event/index.html @@ -0,0 +1,210 @@ +--- +title: Event +slug: Web/API/Event +tags: + - API + - DOM + - Event + - Interface + - NeedsTranslation + - Reference + - Référence(2) + - TopicStub +translation_of: Web/API/Event +--- +<p>{{APIRef("DOM")}}</p> + +<p><code><strong>Event</strong></code> 介面表示了一個在 DOM 物件上所發生的事件。</p> + +<p>一個事件可以是由使用者的操作行為所產生（如：點擊滑鼠按鈕或敲打鍵盤），或是來自 API 因處理非同步任務所產生。事件也可以為程式所觸發，例如呼叫元素的 <a href="https://developer.mozilla.org/zh-TW/docs/Web/API/HTMLElement/click" title="The HTMLElement.click() method simulates a mouse click on an element."><code>HTMLElement.click()</code></a> 方法，或是自行定義事件並使用 <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/dispatchEvent" title="Dispatches an Event at the specified EventTarget, (synchronously) invoking the affected EventListeners in the appropriate order. The normal event processing rules (including the capturing and optional bubbling phase) also apply to events dispatched manually with dispatchEvent()."><code>EventTarget.dispatchEvent()</code></a> 發送至特定的目標。</p> + +<p>事件有多種不同的類型，部分事件是使用基於 <code>Event</code> 的子介面。<code>Event</code> 本身包含了所有事件共同的屬性及方法。</p> + +<p>許多 DOM 元素可被設定接受（accept，或稱為 listen "監聽"）這些事件，並在發生時執行處理（process、handle）事件的程式碼。事件處理器（Event-handlers）通常會使用 <code>EventTarget.addEventListener()</code> 來被連結（connected，或稱為 attached "附加"）至各個 <a href="https://developer.mozilla.org/zh-TW/docs/Web/HTML/Element">HTML 元素</a>（例如 <button>、<div>、<div>、<span> 等），且此方式一般也是用來取代舊的 HTML <a href="https://developer.mozilla.org/zh-TW/docs/HTML/Global_attributes">事件處理器屬性（attributes）</a>。此外，在需要時也可以使用 <a href="https://developer.mozilla.org/zh-TW/docs/Web/API/EventTarget/removeEventListener" title="The EventTarget.removeEventListener() method removes from the EventTarget an event listener previously registered with EventTarget.addEventListener(). The event listener to be removed is identified using a combination of the event type, the event listener function itself, and various optional options that may affect the matching process; see Matching event listeners for removal"><code>removeEventListener()</code></a> 來中斷事件處理器與元素的連結。請留意一個元素可以擁有多個事件處理器（即使是處理同一種事件的不同處理器），特別是那些被切分開來彼此獨立且有不同目標的程式模組（舉例來說，廣告及統計模組可以同時監控網頁中的影片觀看資訊）。</p> + +<p>When there are many nested elements, each with its own handler(s), event processing can become very complicated -- especially where a parent element receives the very same event as its child elements because "spatially" they overlap so the event technically occurs in both, and the processing order of such events depends on the <a href="https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events#Event_bubbling_and_capture">Event bubbling and capture</a> settings of each handler triggered.</p> + +<h2 id="Introduction" name="Introduction">基於 <code>Event</code> 的子介面</h2> + +<p>Below is a list of interfaces which are based on the main <code>Event</code> interface, with links to their respective documentation in the MDN API reference. Note that all event interfaces have names which end in "Event".</p> + +<div class="index"> +<ul> + <li>{{domxref("AnimationEvent")}}</li> + <li>{{domxref("AudioProcessingEvent")}}</li> + <li>{{domxref("BeforeInputEvent")}}</li> + <li>{{domxref("BeforeUnloadEvent")}}</li> + <li>{{domxref("BlobEvent")}}</li> + <li>{{domxref("ClipboardEvent")}}</li> + <li>{{domxref("CloseEvent")}}</li> + <li>{{domxref("CompositionEvent")}}</li> + <li>{{domxref("CSSFontFaceLoadEvent")}}</li> + <li>{{domxref("CustomEvent")}}</li> + <li>{{domxref("DeviceLightEvent")}}</li> + <li>{{domxref("DeviceMotionEvent")}}</li> + <li>{{domxref("DeviceOrientationEvent")}}</li> + <li>{{domxref("DeviceProximityEvent")}}</li> + <li>{{domxref("DOMTransactionEvent")}}</li> + <li>{{domxref("DragEvent")}}</li> + <li>{{domxref("EditingBeforeInputEvent")}}</li> + <li>{{domxref("ErrorEvent")}}</li> + <li>{{domxref("FetchEvent")}}</li> + <li>{{domxref("FocusEvent")}}</li> + <li>{{domxref("GamepadEvent")}}</li> + <li>{{domxref("HashChangeEvent")}}</li> + <li>{{domxref("IDBVersionChangeEvent")}}</li> + <li>{{domxref("InputEvent")}}</li> + <li>{{domxref("KeyboardEvent")}}</li> + <li>{{domxref("MediaStreamEvent")}}</li> + <li>{{domxref("MessageEvent")}}</li> + <li>{{domxref("MouseEvent")}}</li> + <li>{{domxref("MutationEvent")}}</li> + <li>{{domxref("OfflineAudioCompletionEvent")}}</li> + <li>{{domxref("OverconstrainedError")}}</li> + <li>{{domxref("PageTransitionEvent")}}</li> + <li>{{domxref("PaymentRequestUpdateEvent")}}</li> + <li>{{domxref("PointerEvent")}}</li> + <li>{{domxref("PopStateEvent")}}</li> + <li>{{domxref("ProgressEvent")}}</li> + <li>{{domxref("RelatedEvent")}}</li> + <li>{{domxref("RTCDataChannelEvent")}}</li> + <li>{{domxref("RTCIdentityErrorEvent")}}</li> + <li>{{domxref("RTCIdentityEvent")}}</li> + <li>{{domxref("RTCPeerConnectionIceEvent")}}</li> + <li>{{domxref("SensorEvent")}}</li> + <li>{{domxref("StorageEvent")}}</li> + <li>{{domxref("SVGEvent")}}</li> + <li>{{domxref("SVGZoomEvent")}}</li> + <li>{{domxref("TimeEvent")}}</li> + <li>{{domxref("TouchEvent")}}</li> + <li>{{domxref("TrackEvent")}}</li> + <li>{{domxref("TransitionEvent")}}</li> + <li>{{domxref("UIEvent")}}</li> + <li>{{domxref("UserProximityEvent")}}</li> + <li>{{domxref("WebGLContextEvent")}}</li> + <li>{{domxref("WheelEvent")}}</li> +</ul> +</div> + +<h2 id="Constructor" name="Constructor">建構式</h2> + +<dl> + <dt>{{domxref("Event.Event", "Event()")}}</dt> + <dd>建立一個 <code>Event</code> 物件。</dd> +</dl> + +<h2 id="屬性" name="屬性">屬性</h2> + +<dl> + <dt>{{domxref("Event.bubbles")}} {{readonlyinline}}</dt> + <dd>布林值，表示事件是否會向上冒泡傳遞。</dd> + <dt>{{domxref("Event.cancelBubble")}}</dt> + <dd>由於歷史性因素，此屬性的效果等同於 {{domxref("Event.stopPropagation()", "stopPropagation()")}} 方法。若在事件處理器回傳前設定此值為 <code>true</code>，可阻止事件繼續向上冒泡傳遞。</dd> + <dt>{{domxref("Event.cancelable")}} {{readonlyinline}}</dt> + <dd>布林值，表示事件是否能被取消。</dd> + <dt>{{domxref("Event.composed")}} {{ReadOnlyInline}}</dt> + <dd>A Boolean value indicating whether or not the event can bubble across the boundary between the shadow DOM and the regular DOM.</dd> + <dt>{{domxref("Event.currentTarget")}} {{readonlyinline}}</dt> + <dd>指向目前處理事件之監聽器所屬的 DOM 物件。</dd> + <dt>{{domxref("Event.deepPath")}} {{non-standard_inline}}</dt> + <dd>An {{jsxref("Array")}} of DOM {{domxref("Node")}}s through which the event has bubbled.</dd> + <dt>{{domxref("Event.defaultPrevented")}} {{readonlyinline}}</dt> + <dd>布林值，表示事件的預設行為是否被 {{domxref("event.preventDefault()", "preventDefault()")}} 方法所取消。</dd> + <dt>{{domxref("Event.eventPhase")}} {{readonlyinline}}</dt> + <dd>表示事件目前的傳遞階段。</dd> + <dt>{{domxref("Event.explicitOriginalTarget")}} {{non-standard_inline}} {{readonlyinline}}</dt> + <dd>事件的明確原定目標（Mozilla 專屬）。</dd> + <dt>{{domxref("Event.originalTarget")}} {{non-standard_inline}} {{readonlyinline}}</dt> + <dd>事件重新導向前的原定目標（Mozilla 專屬）。</dd> + <dt>{{domxref("Event.returnValue")}}</dt> + <dd>非標準屬性。用以替代 {{domxref("Event.preventDefault()", "preventDefault()")}} 方法與 {{domxref("Event.defaultPrevented", "defaultPrevented")}} 屬性（舊版 Internet Explorer 專屬）。</dd> + <dt>{{domxref("Event.scoped")}} {{readonlyinline}} {{obsolete_inline}}</dt> + <dd>A {{jsxref("Boolean")}} indicating whether the given event will bubble across through the shadow root into the standard DOM. This property has been renamed to {{domxref("Event.composed", "composed")}}.</dd> + <dt>{{domxref("Event.srcElement")}} {{non-standard_inline}}</dt> + <dd>非標準屬性。為 {{domxref("Event.target", "target")}} 屬性的別名（舊版 Internet Explorer 專屬）。</dd> + <dt>{{domxref("Event.target")}} {{readonlyinline}}</dt> + <dd>指向最初觸發事件的 DOM 物件。</dd> + <dt>{{domxref("Event.timeStamp")}} {{readonlyinline}}</dt> + <dd>事件發生（事件物件建立）至今的時間。</dd> + <dt>{{domxref("Event.type")}} {{readonlyinline}}</dt> + <dd>事件類型（不區分大小寫）。</dd> + <dt>{{domxref("Event.isTrusted")}} {{readonlyinline}}</dt> + <dd>表示事件物件是否為瀏覽器建立（比如在用戶點擊之後），或由程式碼所建立（使用建立事件的方法，如 {{domxref("Event.initEvent()", "initEvent()")}}）。</dd> +</dl> + +<h3 id="Obsolete_properties">Obsolete properties</h3> + +<dl> + <dt>{{domxref("Event.scoped")}} {{readonlyinline}} {{obsolete_inline}}</dt> + <dd>A {{jsxref("Boolean")}} indicating whether the given event will bubble across through the shadow root into the standard DOM. This property has been renamed to {{domxref("Event.composed", "composed")}}.</dd> +</dl> + +<h2 id="方法" name="方法">方法</h2> + +<dl> + <dt>{{domxref("Event.createEvent()")}} {{deprecated_inline}}</dt> + <dd> + <p>Creates a new event, which must then be initialized by calling its <code>initEvent()</code> method.</p> + </dd> + <dt>{{domxref("Event.composedPath()")}}</dt> + <dd>Returns the event’s path (objects on which listeners will be invoked). This does not include nodes in shadow trees if the shadow root was created with its {{domxref("ShadowRoot.mode")}} closed.</dd> +</dl> + +<dl> + <dt>{{domxref("Event.initEvent()")}} {{deprecated_inline}}</dt> + <dd>初始化已經建立的事件。若該事件已經被處理過，這方法就不會執行任何東西。</dd> + <dt>{{domxref("Event.preventDefault()")}}</dt> + <dd>取消該事件（如果該事件的 {{domxref("Event.cancelable", "cancelable")}} 屬性為 <code>true</code>）。</dd> + <dt>{{domxref("Event.stopImmediatePropagation()")}}</dt> + <dd>一旦事件物件呼叫此方法，目前元素中尚未執行的已註冊之相同事件類型監聽器將不會被呼叫，而事件也不會繼續捕捉或冒泡傳遞。</dd> + <dt>{{domxref("Event.stopPropagation()")}}</dt> + <dd>阻止事件物件繼續捕捉或冒泡傳遞。</dd> +</dl> + +<h3 id="已廢棄方法">已廢棄方法</h3> + +<dl> + <dt>{{domxref("Event.getPreventDefault()")}} {{non-standard_inline}}</dt> + <dd>非標準方法。回傳 <code>defaultPrevented</code> 屬性值。請直接改用 {{domxref("Event.defaultPrevented", "defaultPrevented")}} 屬性。</dd> + <dt>{{domxref("Event.preventBubble()")}} {{non-standard_inline}} {{Obsolete_inline(24)}}</dt> + <dd>已廢棄方法。阻止事件繼續冒泡傳遞。請改用 {{domxref("event.stopPropagation()", "stopPropagation()")}} 方法。</dd> + <dt>{{domxref("Event.preventCapture()")}} {{non-standard_inline}} {{Obsolete_inline(24)}}</dt> + <dd>已廢棄方法。請改用 {{domxref("event.stopPropagation()", "stopPropagation()")}} 方法。</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('DOM WHATWG', '#interface-event', 'Event')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + + + +<p>{{Compat("api.Event")}}</p> + +<h2 id="See_also" name="See_also">參見</h2> + +<ul> + <li>可用的事件類型：<a href="/zh-TW/docs/Web/Reference/Events">Event reference</a></li> + <li><a href="/zh-TW/docs/Web/API/Event/Comparison_of_Event_Targets">各種 Event Targets 的比較</a> (target vs currentTarget vs relatedTarget vs originalTarget)</li> + <li><a href="/zh-TW/docs/Web/Guide/Events/Creating_and_triggering_events">建立和觸發事件</a></li> + <li>給 Firefox 插件開發者： + <ul> + <li><a href="/zh-TW/docs/Listening_to_events_in_Firefox_extensions">Listening to events in Firefox extensions</a></li> + <li><a href="/zh-TW/docs/Listening_to_events_on_all_tabs">Listening to events on all tabs</a></li> + </ul> + </li> +</ul> diff --git a/files/zh-tw/web/api/event/istrusted/index.html b/files/zh-tw/web/api/event/istrusted/index.html new file mode 100644 index 0000000000..fe35fcc393 --- /dev/null +++ b/files/zh-tw/web/api/event/istrusted/index.html @@ -0,0 +1,107 @@ +--- +title: Event.isTrusted +slug: Web/API/Event/isTrusted +translation_of: Web/API/Event/isTrusted +--- +<p>{{APIRef("DOM")}}</p> + +<p>{{domxref("Event")}} 介面的 <code>isTrusted</code> 唯讀屬性為一個布林值，若事件物件是由使用者操作而產生，則 <code>isTrusted</code> 值為 <code>true</code>。若事件物件是由程式碼所建立、修改，或是透過 {{domxref("EventTarget.dispatchEvent()")}} 來觸發，則 <code>isTrusted</code> 值為 <code>false</code>。</p> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox">var bool = event.isTrusted; +</pre> + +<h2 id="範例">範例</h2> + +<pre> if (e.isTrusted) { + /* The event is trusted. */ + } else { + /* The event is not trusted. */ + } +</pre> + +<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('DOM WHATWG', '#dom-event-istrusted', 'Event.isTrusted')}}</td> + <td>{{ Spec2('DOM WHATWG') }}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM3 Events', '#trusted-events', 'Trusted events')}}</td> + <td>{{Spec2('DOM3 Events')}}</td> + <td>Adds requirements regarding trusted and untrusted events, though it does not itself define the <code>isTrusted</code> property.</td> + </tr> + <tr> + <td>{{SpecName('DOM4', '#dom-event-istrusted', 'Event.isTrusted')}}</td> + <td>{{Spec2('DOM4')}}</td> + <td>Initial definition.</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatChrome(46.0)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}} [1]</td> + <td>{{CompatOpera(33)}}</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</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>{{CompatUnknown}}</td> + <td>{{CompatChrome(46.0)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatOperaMobile(33)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatChrome(46.0)}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] In Internet Explorer, all events are trusted except those that are created with the <code>createEvent()</code> method.</p> diff --git a/files/zh-tw/web/api/event/preventdefault/index.html b/files/zh-tw/web/api/event/preventdefault/index.html new file mode 100644 index 0000000000..8553f5a23a --- /dev/null +++ b/files/zh-tw/web/api/event/preventdefault/index.html @@ -0,0 +1,129 @@ +--- +title: Event.preventDefault() +slug: Web/API/Event/preventDefault +translation_of: Web/API/Event/preventDefault +--- +<div>{{ ApiRef("DOM") }}</div> + +<div> </div> + +<h2 id="Summary" name="Summary">概要</h2> + +<p>如果事件可以被取消，就取消事件（即取消事件的預設行為）。但不會影響事件的傳遞，事件仍會繼續傳遞。</p> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox"><em>event</em>.preventDefault();</pre> + +<h2 id="Example" name="Example">範例</h2> + +<p>Toggling a checkbox is the default action of clicking on a checkbox. This example demonstrates how to prevent that from happening:</p> + +<pre class="brush: html"><!DOCTYPE html> +<html> +<head> +<title>preventDefault example</title> +</head> + +<body> + <p>Please click on the checkbox control.</p> + <form> + <label for="id-checkbox">Checkbox</label> + <input type="checkbox" id="id-checkbox"/> + </form> + <script> + document.querySelector("#id-checkbox").addEventListener("click", function(event){ + alert("preventDefault will stop you from checking this checkbox!") + event.preventDefault(); + }, false); + </script> +</body> +</html></pre> + +<p>You can see <code>preventDefault</code> in action <a class="internal" href="/samples/domref/dispatchEvent.html" title="samples/domref/dispatchEvent.html">here</a>.</p> + +<p>The following example demonstrates how invalid text input can be stopped from reaching the input field with preventDefault().</p> + +<div id="preventDefault_invalid_text"> +<pre class="brush: html"><!DOCTYPE html> +<html> +<head> +<title>preventDefault example</title> + +<script> +</pre> + +<pre class="brush: js">function Init () { + var myTextbox = document.getElementById('my-textbox'); + myTextbox.addEventListener( 'keypress', checkName, false ); +} + +function checkName(evt) { + var charCode = evt.charCode; + if (charCode != 0) { + if (charCode < 97 || charCode > 122) { + evt.preventDefault(); + alert( + "Please use lowercase letters only." + + "\n" + "charCode: " + charCode + "\n" + ); + } + } +} +</pre> + +<pre class="brush: html"></script> +</head> +<body onload="Init ()"> + <p>Please enter your name using lowercase letters only.</p> + <form> + <input type="text" id="my-textbox" /> + </form> +</body> +</html></pre> +</div> + +<p>Here is the result of the preceding code:</p> + +<p>{{ EmbedLiveSample('preventDefault_invalid_text', '', '', '') }}</p> + +<h2 id="Notes" name="Notes">備註</h2> + +<p>Calling <code>preventDefault</code> during any stage of event flow cancels the event, meaning that any default action normally taken by the implementation as a result of the event will not occur.</p> + +<div class="note"> +<p><strong>Note:</strong> As of {{Gecko("6.0")}}, calling <code>preventDefault()</code> causes the {{ domxref("event.defaultPrevented") }} property's value to become <code>true</code>.</p> +</div> + +<p>你可以查看 {{domxref("Event.cancelable")}} 屬性來檢查事件是否能夠被取消。對一個不能被取消的事件呼叫 <code>preventDefault()</code> 方法是沒有任何效果的。</p> + +<p><code>preventDefault()</code> 方法不會停止事件傳遞。若要停止事件繼續傳遞，可以使用 {{domxref("Event.stopPropagation()")}} 方法。</p> + +<h2 id="Specifications" name="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('DOM WHATWG', '#dom-event-preventdefault', 'Event.preventDefault()')}}</td> + <td>{{ Spec2('DOM WHATWG') }}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM4', '#dom-event-preventdefault', 'Event.preventDefault()')}}</td> + <td>{{ Spec2('DOM4') }}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM2 Events', '#Events-Event-preventDefault', 'Event.preventDefault()')}}</td> + <td>{{ Spec2('DOM2 Events') }}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> diff --git a/files/zh-tw/web/api/event/stopimmediatepropagation/index.html b/files/zh-tw/web/api/event/stopimmediatepropagation/index.html new file mode 100644 index 0000000000..8b08a441cc --- /dev/null +++ b/files/zh-tw/web/api/event/stopimmediatepropagation/index.html @@ -0,0 +1,94 @@ +--- +title: Event.stopImmediatePropagation() +slug: Web/API/Event/stopImmediatePropagation +tags: + - API + - Event +translation_of: Web/API/Event/stopImmediatePropagation +--- +<p>{{APIRef("DOM")}}</p> + +<p>除了停止事件繼續捕捉或冒泡傳遞外，也阻止事件被傳入同元素中註冊的其它相同事件類型之監聽器。</p> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="eval">event.stopImmediatePropagation(); +</pre> + +<h2 id="Notes" name="Notes">備註</h2> + +<p>如果一個元素中註冊了多個相同事件類型的監聽器，監聽器將會按照註冊的先後順序被呼叫。在其中任何一個監聽器執行的期間，若是呼叫了事件物件的 <code>stopImmediatePropagation()</code> 方法，則接下來尚未執行的監聽器皆不會被呼叫。</p> + +<h2 id="規範">規範</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('DOM WHATWG', '#dom-event-stopimmediatepropagation', 'Event.stopImmediatePropagation()')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM4', '#dom-event-stopimmediatepropagation', 'Event.stopImmediatePropagation()')}}</td> + <td>{{Spec2('DOM4')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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("6.0")}}</td> + <td>{{CompatGeckoDesktop("10.0")}}</td> + <td>{{CompatIE(9.0)}}</td> + <td>{{CompatOpera("15.0")}}</td> + <td>{{CompatSafari("5.0")}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> diff --git a/files/zh-tw/web/api/event/stoppropagation/index.html b/files/zh-tw/web/api/event/stoppropagation/index.html new file mode 100644 index 0000000000..652231306b --- /dev/null +++ b/files/zh-tw/web/api/event/stoppropagation/index.html @@ -0,0 +1,63 @@ +--- +title: Event.stopPropagation() +slug: Web/API/Event/stopPropagation +tags: + - API + - DOM + - Event + - Method + - NeedsRewrite + - Reference +translation_of: Web/API/Event/stopPropagation +--- +<div>{{APIRef("DOM")}}</div> + +<p>{{domxref("Event")}} 介面的 <strong><code>stopPropagation()</code></strong> 方法可阻止當前事件繼續進行捕捉（capturing）及冒泡（bubbling）階段的傳遞。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><em>event</em>.stopPropagation();</pre> + +<h2 id="範例">範例</h2> + +<p>請參考範例五：<a href="https://developer.mozilla.org/en-US/docs/DOM/DOM_Reference/Examples#Example_5:_Event_Propagation">事件傳遞</a>章節中關於此方法與 DOM 事件傳遞的更詳細範例。</p> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th>Specification</th> + <th>Status</th> + <th>Comment</th> + </tr> + <tr> + <td>{{SpecName("DOM WHATWG", "#dom-event-stoppropagation", "Event.stopPropagation()")}}</td> + <td>{{Spec2("DOM WHATWG")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("DOM4", "#dom-event-stoppropagation", "Event.stopPropagation()")}}</td> + <td>{{Spec2("DOM4")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("DOM2 Events", "#Events-Event-stopPropagation", "Event.stopPropagation()")}}</td> + <td>{{Spec2("DOM2 Events")}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + + + +<p>{{Compat("api.Event.stopPropagation")}}</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>See the <a href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-flow-capture">DOM specification</a> for the explanation of event flow. (The <a href="http://www.w3.org/TR/DOM-Level-3-Events/#event-flow">DOM Level 3 Events draft</a> has an illustration.)</li> + <li>{{domxref("Event.preventDefault()")}} is a related method that prevents the default action of the event from happening.</li> +</ul> diff --git a/files/zh-tw/web/api/event/target/index.html b/files/zh-tw/web/api/event/target/index.html new file mode 100644 index 0000000000..9599be68c7 --- /dev/null +++ b/files/zh-tw/web/api/event/target/index.html @@ -0,0 +1,134 @@ +--- +title: Event.target +slug: Web/API/Event/target +translation_of: Web/API/Event/target +--- +<p>{{ApiRef("DOM")}}</p> + +<p>指向最初觸發事件的 DOM 物件。與 {{domxref("event.currentTarget")}} 屬性不同的是，<code>event.currentTarget</code> 屬性總會指向目前於冒泡或捕捉階段正在處理該事件之事件處理器所註冊的 DOM 物件，而 <code>event.target</code> 屬性則是永遠指向觸發事件的 DOM 物件。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">theTarget = event.target</pre> + +<h2 id="範例">範例</h2> + +<p>The <code>event.target</code> property can be used in order to implement <strong>event delegation</strong>.</p> + +<pre class="brush: js">// Make a list +var ul = document.createElement('ul'); +document.body.appendChild(ul); + +var li1 = document.createElement('li'); +var li2 = document.createElement('li'); +ul.appendChild(li1); +ul.appendChild(li2); + +function hide(e){ + // e.target refers to the clicked <li> element + // This is different than e.currentTarget which would refer to the parent <ul> in this context + e.target.style.visibility = 'hidden'; +} + +// Attach the listener to the list +// It will fire when each <li> is clicked +ul.addEventListener('click', hide, false); +</pre> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th>Specification</th> + <th>Status</th> + <th>Comment</th> + </tr> + <tr> + <td>{{SpecName("DOM WHATWG", "#dom-event-target", "Event.target")}}</td> + <td>{{Spec2("DOM WHATWG")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("DOM4", "#dom-event-target", "Event.target")}}</td> + <td>{{Spec2("DOM4")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("DOM2 Events", "#Events-Event-target", "Event.target")}}</td> + <td>{{Spec2("DOM2 Events")}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="Compatibility_notes">Compatibility notes</h2> + +<p>On IE 6-8 the event model is different. Event listeners are attached with the non-standard {{domxref('EventTarget.attachEvent')}} method. In this model, the event object has a {{domxref('Event.srcElement')}} property, instead of the <code>target</code> property, and it has the same semantics as <code>event.target</code>.</p> + +<pre class="brush: js">function hide(e) { + // Support IE6-8 + var target = e.target || e.srcElement; + target.style.visibility = 'hidden'; +} +</pre> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/Event/Comparison_of_Event_Targets">Comparison of Event Targets</a></li> +</ul> diff --git a/files/zh-tw/web/api/event/timestamp/index.html b/files/zh-tw/web/api/event/timestamp/index.html new file mode 100644 index 0000000000..3ec006a09e --- /dev/null +++ b/files/zh-tw/web/api/event/timestamp/index.html @@ -0,0 +1,54 @@ +--- +title: Event.timeStamp +slug: Web/API/Event/timeStamp +translation_of: Web/API/Event/timeStamp +--- +<div>{{ApiRef("DOM")}}</div> + +<h2 id="Summary" name="Summary">說明</h2> + +<p>回傳事件建立的時間（單位是毫秒；從 epoch 開始計算）。</p> + +<h2 id="Syntax" name="Syntax">Syntax</h2> + +<pre class="syntaxbox">event.timeStamp +</pre> + +<h2 id="Examples" name="Examples">範例</h2> + +<pre><em>var number</em> = event.timeStamp; +</pre> + +<p>下面是一個較為完整的範例：</p> + +<pre class="brush: html"><html> +<head> + +<title>timeStamp example</title> + +<script type="text/javascript"> +function getTime(event) { + document.getElementById("time").firstChild.nodeValue = event.timeStamp; +} +</script> +</head> + +<body onkeypress="getTime(event)"> + +<p>Press any key to get the current timestamp +for the onkeypress event.</p> +<p>timeStamp: <span id="time">-</span></p> + +</body> +</html> +</pre> + +<h2 id="Notes" name="Notes">注意</h2> + +<p>這個 property 僅在瀏覽器支持該事件才會有用。</p> + +<h2 id="Specification" name="Specification">詳細資料</h2> + +<ul> + <li><a class="external" href="http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-Event-timeStamp">timestamp </a></li> +</ul> diff --git a/files/zh-tw/web/api/event/type/index.html b/files/zh-tw/web/api/event/type/index.html new file mode 100644 index 0000000000..12fcf0176d --- /dev/null +++ b/files/zh-tw/web/api/event/type/index.html @@ -0,0 +1,97 @@ +--- +title: Event.type +slug: Web/API/Event/type +translation_of: Web/API/Event/type +--- +<p>{{APIRef}}</p> + +<p><code><strong>Event.type</strong></code> 唯讀屬性會回傳一個代表此事件物件類型的字串。<code>Event.type</code> 屬性是於事件物件建立時被設定，而其屬性值－事件類型名稱也常被當作是特定的事件。</p> + +<p>傳至 {{ domxref("EventTarget.addEventListener()") }} 和 {{ domxref("EventTarget.removeEventListener()") }} 方法中，代表事件類型的參數 <em><code>event</code></em> 是不區分大小寫的。</p> + +<p>可用的事件類型，可參考 <a href="/zh-TW/docs/Web/Events" title="Mozilla event reference">event reference</a>。</p> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox">event.type +</pre> + +<h2 id="Example" name="Example">範例</h2> + +<pre class="brush: html"><!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="utf-8"> + + <title>Event.type Example</title> + + <script> + var currEvent = null; + function getEvtType(evt) { + console.log("//Start------------getEvtType(evt)------------ "); + + currEvent = evt.type; + console.log(currEvent); + + //document.getElementById("Etype").firstChild.nodeValue = currEvent; + document.getElementById("Etype").innerHTML = currEvent; + + console.log("//End--------------getEvtType(evt)------------ "); + } + + //Keyboard events + document.addEventListener("keypress", getEvtType, false); //[second] + + document.addEventListener("keydown", getEvtType, false); //first + document.addEventListener("keyup", getEvtType, false); //third + + //Mouse events + document.addEventListener("click", getEvtType, false); // third + + document.addEventListener("mousedown", getEvtType, false); //first + document.addEventListener("mouseup", getEvtType, false); //second + + </script> +</head> + +<body> + +<p>Press any key or click the mouse to get the event type.</p> +<p>Event type: <span id="Etype" style="color:red">-</span></p> + +</body> +</html> +</pre> + +<h3 id="Result">Result</h3> + +<p>{{EmbedLiveSample('Example')}}</p> + +<h2 id="Specifications" name="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('DOM WHATWG', '#dom-event-type', 'Event.type')}}</td> + <td>{{ Spec2('DOM WHATWG') }}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM4', '#dom-event-type', 'Event.type')}}</td> + <td>{{ Spec2('DOM4') }}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM2 Events', '#Events-Event-type', 'Event.type')}}</td> + <td>{{ Spec2('DOM2 Events') }}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> diff --git a/files/zh-tw/web/api/eventlistener/index.html b/files/zh-tw/web/api/eventlistener/index.html new file mode 100644 index 0000000000..8db3fba758 --- /dev/null +++ b/files/zh-tw/web/api/eventlistener/index.html @@ -0,0 +1,93 @@ +--- +title: EventListener +slug: Web/API/EventListener +tags: + - DOM + - 事件 + - 事件監聽 +translation_of: Web/API/EventListener +--- +<div>{{APIRef("DOM Events")}}</div> + +<p><strong><code>EventListener</code></strong> 介面表示一個可以處理由 {{domxref("EventTarget")}} 物件分派事件的物件。</p> + +<div class="note"> +<p><strong>注意：</strong>基於相容舊版內容的需要， <code>EventListener</code> 可以接受一個函式及一個帶有 <code>handleEvent()</code> 屬性函式的物件。相關的<a href="#Example">範例</a>顯示在下方。</p> +</div> + +<h2 id="屬性">屬性</h2> + +<p><em>這個介面並不實作且不繼承任何屬性。</em></p> + +<h2 id="方法">方法</h2> + +<p><em>這個介面不繼承任何方法。</em></p> + +<dl> + <dt>{{domxref("EventListener.handleEvent()")}}</dt> + <dd>一個可以在指定類型事件發生時被呼叫的函數。</dd> +</dl> + +<h2 id="範例">範例</h2> + +<h3 id="HTML">HTML</h3> + +<pre class="brush: html"><button id="btn">Click here!</button></pre> + +<h3 id="JavaScript">JavaScript</h3> + +<pre class="brush: js">const buttonElement = document.getElementById('btn'); + +// 透過提供回呼函數的方式對「click」事件新增處理器。 +// 當元素被點選後會出現「Element clicked!」的彈出訊息。 +buttonElement.addEventListener('click', function (event) { + alert('Element clicked through function!'); +}); + +// 基於相容性，一個帶有 `handleEvent` 的非函式物件可被視為處理函式。 +buttonElement.addEventListener('click', { + handleEvent: function (event) { + alert('Element clicked through handleEvent property!'); + } +}); +</pre> + +<h3 id="結果">結果</h3> + +<p>{{EmbedLiveSample('Example')}}</p> + +<h3 id="檢閱相關">檢閱相關:</h3> + +<ul> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener">addEventListener</a></li> +</ul> + +<h2 id="規格">規格</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">規格</th> + <th scope="col">狀態</th> + <th scope="col">註解</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{SpecName('DOM WHATWG', '#callbackdef-eventlistener', 'EventListener')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>No change.</td> + </tr> + <tr> + <td>{{SpecName('DOM2 Events', '#Events-EventListener', 'EventListener')}}</td> + <td>{{Spec2('DOM2 Events')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<div class="hidden">這頁所產生的相容性表格是來自於結構化的資料。如果你想要貢獻資料，請查閱 <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> 並傳送提取要求給我們。</div> + +<p>{{Compat("api.EventListener")}}</p> diff --git a/files/zh-tw/web/api/eventtarget/dispatchevent/index.html b/files/zh-tw/web/api/eventtarget/dispatchevent/index.html new file mode 100644 index 0000000000..8977c22c9e --- /dev/null +++ b/files/zh-tw/web/api/eventtarget/dispatchevent/index.html @@ -0,0 +1,134 @@ +--- +title: EventTarget.dispatchEvent() +slug: Web/API/EventTarget/dispatchEvent +translation_of: Web/API/EventTarget/dispatchEvent +--- +<p>{{APIRef("DOM Events")}}</p> + +<p>於此 {{domxref("EventTarget")}} 物件上觸發特定的 {{domxref("Event")}} 物件實體，相當於依照註冊的順序呼叫它的 {{domxref("EventListener")}}。一般事件處理規則（包含捕捉（capturing）和可選的冒泡（bubbling）階段）也適用於用 <code>dispatchEvent()</code> 手動觸發事件。</p> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox"><em>cancelled</em> = !<em>target</em>.dispatchEvent(<em>event</em>) +</pre> + +<h3 id="參數">參數</h3> + +<ul> + <li><code>event</code> 是要被觸發的事件（{{domxref("Event")}} 物件）。</li> + <li><code>target</code> 會被初始化為事件的 {{domxref("Event", "", "target")}} 屬性，其也影響了要呼叫哪一個事件監聽器。</li> +</ul> + +<h3 id="回傳值">回傳值</h3> + +<ul> + <li>會在事件完成傳遞（捕捉、命中、冒泡三階段）之後才回傳其值。</li> + <li>若事件在傳遞過程當中，事件是可被取消的（{{domxref("Event.cancelable")}} 屬性為 <code>true</code>）且曾於一個或一個以上的事件處理器中被執行了該事件的 {{domxref("Event.preventDefault()")}} 方法（且事件須確實已被取消了預設行為），即回傳 <code>false</code>。否則回傳 <code>true</code> 值。</li> +</ul> + +<p>若遇到以下 3 種情況，<code>dispatchEvent </code>會拋出錯誤資訊－－ <code>UNSPECIFIED_EVENT_TYPE_ERR</code> ：</p> + +<ol> + <li>執行 <code>dispatchEvent</code> 前並未藉由初始化事件指定事件類型</li> + <li>事件類型為 <code>null</code> 。</li> + <li>事件類型是個空白字串。</li> +</ol> + +<p>這些異常，處理器會報告「異常未捕獲（uncaught exceptions）」；</p> + +<p>事件處理器（event handlers）會在一群呼叫堆（nested callstack）上執行：事件的呼叫方（caller）會先由處理器會阻擋暫停執行，直到事件完成才繼續執行，但是要注意的是，事件若發生異常並不會傳回給呼叫方。</p> + +<h2 id="Notes" name="Notes">注意</h2> + +<p><code>dispatchEvent</code> 是「建立→初始化→觸發」的最後一步驟。這些步驟是用來觸發事件，讓事件完成。事件有多種建立方式，例如用 {{domxref("document.createEvent")}} 並用 <a href="/en-US/docs/DOM/event.initEvent" title="DOM/event.initEvent">initEvent</a> 或其他特殊 methods ，像是 <a href="/en-US/docs/DOM/event.initMouseEvent" title="DOM/event.initMouseEvent">initMouseEvent</a> 或 <a href="/en-US/docs/DOM/event.initUIEvent" title="DOM/event.initUIEvent">initUIEvent</a> 來初始化。</p> + +<p>詳請可參考《{{domxref("Event")}}》。</p> + +<h2 id="Example" name="Example">範例</h2> + +<p>請參閱《<a href="/zh-TW/docs/Web/Guide/Events/Creating_and_triggering_events">建立或觸發事件</a>》。</p> + +<h2 id="Specification" name="Specification">規格</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('DOM WHATWG', '#dom-eventtarget-dispatchevent', 'EventTarget.dispatchEvent()')}}</td> + <td>{{ Spec2('DOM WHATWG') }}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM4', '#dom-eventtarget-dispatchevent', 'EventTarget.dispatchEvent()')}}</td> + <td>{{ Spec2('DOM4') }}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM2 Events', '#Events-EventTarget-dispatchEvent', 'EventTarget.dispatchEvent()')}}</td> + <td>{{ Spec2('DOM2 Events') }}</td> + <td>初始定義</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_Compatibility" name="Browser_Compatibility">瀏覽器支援度</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>4</td> + <td>{{CompatVersionUnknown}}</td> + <td>2</td> + <td>9 [1]</td> + <td>9.64 (probably earlier)</td> + <td>3.2 (probably earlier)</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{ CompatUnknown() }}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1]：早期的 IE 版本只支持 IE 特有的 {{domxref("EventTarget.fireEvent()")}} 方法來觸發事件。</p> diff --git a/files/zh-tw/web/api/eventtarget/index.html b/files/zh-tw/web/api/eventtarget/index.html new file mode 100644 index 0000000000..4c10aa133e --- /dev/null +++ b/files/zh-tw/web/api/eventtarget/index.html @@ -0,0 +1,177 @@ +--- +title: EventTarget +slug: Web/API/EventTarget +tags: + - API + - DOM + - DOM Events + - Interface + - NeedsTranslation + - TopicStub + - 待翻譯 +translation_of: Web/API/EventTarget +--- +<p>{{ ApiRef("DOM Events") }}</p> + +<p><strong><code>EventTarget</code></strong> 介面定義了其實作的物件具有接收事件的能力，也可能擁有處理事件的監聽器。</p> + +<p>除了最為常見的 {{domxref("Element")}}、{{domxref("Document")}} 與 {{domxref("Window")}} 繼承或實作了 <code>EventTarget</code> 介面之外，其它的物件還有 {{domxref("XMLHttpRequest")}}、{{domxref("AudioNode")}}、{{domxref("AudioContext")}}⋯等等。</p> + +<p>許多 <code>EventTarget</code>（包括 Element、Document 和 Window）除了透過 {{domxref("EventTarget.addEventListener()", "addEventListener()")}} 方法外，還可藉由 {{domxref("Document_Object_Model", "DOM")}} 物件的屬性（{{Glossary("property/JavaScript", "property")}}）或 <a href="/zh-TW/docs/Web/HTML/Element">HTML 元素</a>屬性（{{Glossary("attribute")}}）來設定<a href="/zh-TW/docs/Web/Guide/DOM/Events/Event_handlers">事件處理器</a>。</p> + +<p>{{InheritanceDiagram}}</p> + +<h2 id="方法" name="方法">方法</h2> + +<dl> + <dt>{{domxref("EventTarget.addEventListener()")}}</dt> + <dd>於 <code>EventTarget</code> 物件上註冊指定事件的監聽器。</dd> + <dt>{{domxref("EventTarget.removeEventListener()")}}</dt> + <dd>移除 <code>EventTarget</code> 物件上的指定事件監聽器。</dd> + <dt>{{domxref("EventTarget.dispatchEvent()")}}</dt> + <dd>對此 <code>EventTarget</code> 物件派送（dispatch）一個事件物件，也就是於此 <code>EventTarget</code> 物件上觸發一個指定的事件物件實體。</dd> +</dl> + +<h3 id="Mozilla_chrome_code_的額外方法">Mozilla chrome code 的額外方法</h3> + +<p>Mozilla extensions for use by JS-implemented event targets to implement on* properties. See also <a href="/docs/Mozilla/WebIDL_bindings">WebIDL bindings</a>.</p> + +<ul> + <li>void <strong>setEventHandler</strong>(DOMString type, EventHandler handler) {{non-standard_inline}}</li> + <li>EventHandler <strong>getEventHandler</strong>(DOMString type) {{non-standard_inline}}</li> +</ul> + +<h2 id="範例">範例</h2> + +<h3 id="_Simple_implementation_of_EventTarget" name="_Simple_implementation_of_EventTarget">Simple implementation of EventTarget</h3> + +<pre class="brush: js">var EventTarget = function() { + this.listeners = {}; +}; + +EventTarget.prototype.listeners = null; +EventTarget.prototype.addEventListener = function(type, callback) { + if (!(type in this.listeners)) { + this.listeners[type] = []; + } + this.listeners[type].push(callback); +}; + +EventTarget.prototype.removeEventListener = function(type, callback) { + if (!(type in this.listeners)) { + return; + } + var stack = this.listeners[type]; + for (var i = 0, l = stack.length; i < l; i++) { + if (stack[i] === callback){ + stack.splice(i, 1); + return; + } + } +}; + +EventTarget.prototype.dispatchEvent = function(event) { + if (!(event.type in this.listeners)) { + return true; + } + var stack = this.listeners[event.type]; + event.target = this; + for (var i = 0, l = stack.length; i < l; i++) { + stack[i].call(this, event); + } + return !event.defaultPrevented; +}; +</pre> + +<p>{{ EmbedLiveSample('_Simple_implementation_of_EventTarget') }}</p> + +<h2 id="Specification" name="Specification">規範</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('DOM WHATWG', '#interface-eventtarget', 'EventTarget')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>No change.</td> + </tr> + <tr> + <td>{{SpecName('DOM3 Events', 'DOM3-Events.html#interface-EventTarget', 'EventTarget')}}</td> + <td>{{Spec2('DOM3 Events')}}</td> + <td>A few parameters are now optional (<code>listener</code>), or accepts the <code>null</code> value (<code>useCapture</code>).</td> + </tr> + <tr> + <td>{{SpecName('DOM2 Events', 'events.html#Events-EventTarget', 'EventTarget')}}</td> + <td>{{Spec2('DOM2 Events')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_Compatibility" name="Browser_Compatibility">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>1.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1")}}</td> + <td>9.0</td> + <td>7</td> + <td>1.0<sup>[1]</sup></td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>1.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("1")}}</td> + <td>9.0</td> + <td>6.0</td> + <td>1.0</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] <code>window.EventTarget</code> does not exist.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/docs/Web/Reference/Events">Event reference</a> - the events available in the platform.</li> + <li><a href="/docs/Web/Guide/DOM/Events">Event developer guide</a></li> + <li>{{domxref("Event")}} interface</li> +</ul> diff --git a/files/zh-tw/web/api/eventtarget/removeeventlistener/index.html b/files/zh-tw/web/api/eventtarget/removeeventlistener/index.html new file mode 100644 index 0000000000..136aa0cf58 --- /dev/null +++ b/files/zh-tw/web/api/eventtarget/removeeventlistener/index.html @@ -0,0 +1,274 @@ +--- +title: EventTarget.removeEventListener() +slug: Web/API/EventTarget/removeEventListener +translation_of: Web/API/EventTarget/removeEventListener +--- +<p>{{APIRef("DOM Events")}}</p> + +<p><strong><code>EventTarget.removeEventListener()</code></strong> 方法可以移除先前由 {{domxref("EventTarget.addEventListener()", "addEventListener()")}} 所註冊的事件監聽器。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><code><em>target</em>.removeEventListener(<em>type</em>, <em>listener</em>[, <em>options</em>]); +</code><em>target</em>.removeEventListener(<em>type</em>, <em>listener</em>[, <em>useCapture</em>]); +</pre> + +<h3 id="參數">參數</h3> + +<dl> + <dt><code>type</code></dt> + <dd>A string representing the event type to remove.</dd> + <dt><code>listener</code></dt> + <dd>The {{domxref("EventListener")}} function to remove from the event target.</dd> + <dt>options {{optional_inline}}</dt> + <dd>An options object that specifies characteristics about the event listener. The available options are: + <ul> + <li><code>capture</code>: A {{jsxref("Boolean")}} that indicates that events of this type will be dispatched to the registered <code>listener</code> before being dispatched to any <code>EventTarget</code> beneath it in the DOM tree. </li> + <li><code>passive</code>: A {{jsxref("Boolean")}} indicating that the <code>listener</code> will never call <code>preventDefault()</code>. If it does, the user agent should ignore it and generate a console warning.</li> + <li>{{non-standard_inline}}<code> mozSystemGroup</code>: Available only in code running in XBL or in Firefox' chrome, it is a {{jsxref("Boolean")}} defining if the listener is added to the system group.</li> + </ul> + </dd> + <dt><code>useCapture</code> {{optional_inline}}</dt> + <dd>Specifies whether the {{domxref("EventListener")}} to be removed is registered as a capturing listener or not. If this parameter is absent, a default value of <code>false</code> is assumed.</dd> + <dd>If a listener is registered twice, one with capture and one without, remove each one separately. Removal of a capturing listener does not affect a non-capturing version of the same listener, and vice versa.</dd> +</dl> + +<div class="note"><strong>Note:</strong> <code>useCapture</code> was required in most major browsers' early versions. If broad compatibility is desired, you should always provide the <code>useCapture</code> parameter.</div> + +<h3 id="回傳值">回傳值</h3> + +<p>無。</p> + +<h2 id="備註">備註</h2> + +<p>If an {{domxref("EventListener")}} is removed from an {{domxref("EventTarget")}} while it is processing an event, it will not be triggered by the current actions. An {{domxref("EventListener")}} will not be invoked for the event it was registered for after being removed, however it can be reattached.</p> + +<p>Calling <code>removeEventListener()</code> with arguments that do not identify any currently registered {{domxref("EventListener")}} on the <code>EventTarget</code> has no effect.</p> + +<h2 id="範例">範例</h2> + +<p>This example shows how to add a <code>click</code>-based event listener and remove a <code>mouseover</code>-based event listener.</p> + +<pre class="brush: js">var body = + document.querySelector('body'), + clickTarget = + document.getElementById('click-target'), + mouseOverTarget = + document.getElementById('mouse-over-target'), + toggle = false; + +function makeBackgroundYellow() { + 'use strict'; + + if (toggle) { + body.style.backgroundColor = 'white'; + } else { + body.style.backgroundColor = 'yellow'; + } + + toggle = !toggle; +} + +clickTarget.addEventListener('click', + makeBackgroundYellow, + false +); + +mouseOverTarget.addEventListener('mouseover', function () { + 'use strict'; + + clickTarget.removeEventListener('click', + makeBackgroundYellow, + false + ); +}); +</pre> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th>Specification</th> + <th>Status</th> + <th>Comment</th> + </tr> + <tr> + <td>{{SpecName("DOM WHATWG", "#dom-eventtarget-removeeventlistener", "EventTarget.removeEventListener()")}}</td> + <td>{{Spec2("DOM WHATWG")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("DOM4", "#dom-eventtarget-removeeventlistener", "EventTarget.removeEventListener()")}}</td> + <td>{{Spec2("DOM4")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("DOM2 Events", "#Events-EventTarget-removeEventListener", "EventTarget.removeEventListener()")}}</td> + <td>{{Spec2("DOM2 Events")}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>1.0<sup>[1][2]</sup></td> + <td>{{CompatGeckoDesktop("1")}}<sup>[3]</sup></td> + <td>9.0</td> + <td>7<sup>[4]</sup></td> + <td>1.0<sup>[1]</sup></td> + </tr> + <tr> + <td><code>useCapture</code> made optional</td> + <td>{{CompatVersionUnknown}}</td> + <td>6.0</td> + <td>9.0</td> + <td>11.60</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>options</code> parameter</td> + <td>{{CompatChrome(49.0)}}</td> + <td> </td> + <td> </td> + <td> </td> + <td> </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>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + <th>Chrome for Android</th> + </tr> + <tr> + <td>Basic support</td> + <td>1.0<sup>[1]</sup></td> + <td>{{CompatVersionUnknown}}<sup>[2]</sup></td> + <td>{{CompatGeckoMobile("1")}}<sup>[3]</sup></td> + <td>9.0</td> + <td>6.0<sup>[4]</sup></td> + <td>1.0<sup>[1]</sup></td> + <td>{{CompatVersionUnknown}}<sup>[2]</sup></td> + </tr> + <tr> + <td><code>useCapture</code> made optional</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td> </td> + <td> </td> + <td> </td> + <td> </td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>options</code> parameter</td> + <td>{{CompatNo}}</td> + <td>{{CompatChrome(49.0)}}</td> + <td> </td> + <td> </td> + <td> </td> + <td> </td> + <td>{{CompatChrome(49.0)}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Although WebKit explicitly added "<code>[optional]</code>" to the <code>useCapture</code> parameter for Safari 5.1 and Chrome 13, it had been working before the change.</p> + +<p>[2] Before Chrome 49, the type and listener parameters were optional.</p> + +<p>[2] Prior to Firefox 6, the browser would throw an exception if the <code>useCapture</code> parameter was not explicitly <code>false</code>. Prior to Gecko 9.0 {{geckoRelease("9.0")}}, <code>addEventListener()</code> would throw an exception if the listener parameter was <code>null</code>; now the method returns without error, but without doing anything.</p> + +<p>[4] Opera 11.60 made the <code>useCapture</code> parameter optional (<a href="http://my.opera.com/ODIN/blog/2011/09/29/what-s-new-in-opera-development-snapshots-28-september-2011-edition">source</a>).</p> + +<p>[5] For backwards compatibility, browsers that support <code>options</code> allow the third parameter to be either <code>options</code> or <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean" title="The Boolean object is an object wrapper for a boolean value."><code>Boolean</code></a>.</p> + +<h2 id="Polyfill_to_support_older_browsers">Polyfill to support older browsers</h2> + +<p><code>addEventListener()</code> and <code>removeEventListener()</code> are not present in older browsers. You can work around this by inserting the following code at the beginning of your scripts, allowing the use of <code>addEventListener()</code> and <code>removeEventListener()</code> in implementations that do not natively support it. However, this method will not work on Internet Explorer 7 or earlier, since extending the Element.prototype was not supported until Internet Explorer 8.</p> + +<pre class="brush: js">if (!Element.prototype.addEventListener) { + var oListeners = {}; + function runListeners(oEvent) { + if (!oEvent) { oEvent = window.event; } + for (var iLstId = 0, iElId = 0, oEvtListeners = oListeners[oEvent.type]; iElId < oEvtListeners.aEls.length; iElId++) { + if (oEvtListeners.aEls[iElId] === this) { + for (iLstId; iLstId < oEvtListeners.aEvts[iElId].length; iLstId++) { oEvtListeners.aEvts[iElId][iLstId].call(this, oEvent); } + break; + } + } + } + Element.prototype.addEventListener = function (sEventType, fListener /*, useCapture (will be ignored!) */) { + if (oListeners.hasOwnProperty(sEventType)) { + var oEvtListeners = oListeners[sEventType]; + for (var nElIdx = -1, iElId = 0; iElId < oEvtListeners.aEls.length; iElId++) { + if (oEvtListeners.aEls[iElId] === this) { nElIdx = iElId; break; } + } + if (nElIdx === -1) { + oEvtListeners.aEls.push(this); + oEvtListeners.aEvts.push([fListener]); + this["on" + sEventType] = runListeners; + } else { + var aElListeners = oEvtListeners.aEvts[nElIdx]; + if (this["on" + sEventType] !== runListeners) { + aElListeners.splice(0); + this["on" + sEventType] = runListeners; + } + for (var iLstId = 0; iLstId < aElListeners.length; iLstId++) { + if (aElListeners[iLstId] === fListener) { return; } + } + aElListeners.push(fListener); + } + } else { + oListeners[sEventType] = { aEls: [this], aEvts: [ [fListener] ] }; + this["on" + sEventType] = runListeners; + } + }; + Element.prototype.removeEventListener = function (sEventType, fListener /*, useCapture (will be ignored!) */) { + if (!oListeners.hasOwnProperty(sEventType)) { return; } + var oEvtListeners = oListeners[sEventType]; + for (var nElIdx = -1, iElId = 0; iElId < oEvtListeners.aEls.length; iElId++) { + if (oEvtListeners.aEls[iElId] === this) { nElIdx = iElId; break; } + } + if (nElIdx === -1) { return; } + for (var iLstId = 0, aElListeners = oEvtListeners.aEvts[nElIdx]; iLstId < aElListeners.length; iLstId++) { + if (aElListeners[iLstId] === fListener) { aElListeners.splice(iLstId, 1); } + } + }; +} +</pre> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("EventTarget.addEventListener()")}}.</li> + <li>{{non-standard_inline}}{{domxref("EventTarget.detachEvent()")}}.</li> +</ul> diff --git a/files/zh-tw/web/api/fetch_api/index.html b/files/zh-tw/web/api/fetch_api/index.html new file mode 100644 index 0000000000..2cd6f23d22 --- /dev/null +++ b/files/zh-tw/web/api/fetch_api/index.html @@ -0,0 +1,84 @@ +--- +title: Fetch API +slug: Web/API/Fetch_API +translation_of: Web/API/Fetch_API +--- +<div>{{DefaultAPISidebar("Fetch API")}}</div> + +<div>Fetch API 提供了一個能獲取包含跨網路資源在的資源介面。它有點像我們所熟悉的 {{domxref("XMLHttpRequest")}} ，但這個新的 API 提供了更強更彈性的功能。</div> + +<h2 id="概念與應用">概念與應用</h2> + +<p>Fetch 提供了 {{domxref("Request")}} 與 {{domxref("Response")}} 物件，還有其他牽涉網路請求的通用定義。這能讓他們在需要的時候被使用到，不管是 service worker、Cache API、還是其他處理或更動請求回應的相類事物、或是任何需要產生有序化產生回應的用例（use case）。</p> + +<p>它也提供了諸如 CORS 與 HTTP origin 標頭語意的分散定義，能取代分散的定義。</p> + +<p>要發動請求並取得資源的話，請使用 {{domxref("GlobalFetch.fetch")}} 方法。他實作了數種介面，並指定了 {{domxref("Window")}} 與 {{domxref("WorkerGlobalScope")}}，使它可以在任何想獲取資源的環境中使用。</p> + +<p><code>fetch()</code> 方法有一個強制性的參數，就是要取得資源的網址。該方法會回傳一個不論請求成敗，都會 resolve 的 promise {{domxref("Response","回應")}}。你也能選擇性地使用第二個稱為 <code>init</code> 的物件參數（請參見 {{domxref("Request")}}）。</p> + +<p>當 {{domxref("Response")}} 檢索後，在請求體裡面會定義一些請求體為何，還有要如何處理的方法（請參見 {{domxref("Body")}}）。</p> + +<p>你也可以直接用 {{domxref("Request.Request","Request()")}} 與 {{domxref("Response.Response","Response()")}} 建構子來建立請求與回應，不過你不太可能直接使用他，反而更可能是以其他 API 行動的結果為形式存在。（例如來自 service worker 的 {{domxref("FetchEvent.respondWith")}}）</p> + +<div class="note"> +<p><strong>注意</strong>：你可以在<a href="/zh-TW/docs/Web/API/Fetch_API/Using_Fetch">使用 Fetch</a>深入理解 Fetch，並在<a href="/zh-TW/docs/Web/API/Fetch_API/Basic_concepts">Fetch 的基本概念</a>文章內理解概念。</p> +</div> + +<h3 id="中斷一次_Fetch">中斷一次 Fetch</h3> + +<p>各家瀏覽器已經開始加入 {{DOMxRef("AbortController")}} 與 {{DOMxRef("AbortSignal")}} 介面（也就是 Abort API）的實驗性支援，讓 Fetch 和 XHR 這類的操作在完成前可以被中斷。詳情請參閱相關介面的文件。</p> + +<h2 id="Fetch_介面">Fetch 介面</h2> + +<dl> + <dt>{{DOMxRef("WindowOrWorkerGlobalScope.fetch()")}}</dt> + <dd>用於取得資源的 <code>fetch()</code> 方法。</dd> + <dt>{{domxref("Headers")}}</dt> + <dd>代表請求/回應標頭，讓你能 query 並針對結果不同，採取不同行動。</dd> + <dt>{{domxref("Request")}}</dt> + <dd>代表資源請求。</dd> + <dt>{{domxref("Response")}}</dt> + <dd>代表資源請求的回應。</dd> +</dl> + +<h2 id="Fetch_mixin">Fetch mixin</h2> + +<dl> + <dt>{{domxref("Body")}}</dt> + <dd>提供請求/回應訊息體的相關方法，能宣告內容的類別為何，以及該如何處理。</dd> +</dl> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">註解</th> + </tr> + <tr> + <td>{{SpecName('Fetch')}}</td> + <td>{{Spec2('Fetch')}}</td> + <td>初始定義</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<div class="hidden">The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.</div> + +<p>{{Compat("api.WindowOrWorkerGlobalScope.fetch")}}</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/zh-TW/docs/Web/API/Fetch_API/Using_Fetch">使用 Fetch</a></li> + <li><a href="/zh-TW/docs/Web/API/ServiceWorker_API">ServiceWorker API</a></li> + <li><a href="/zh-TW/docs/Web/HTTP/Access_control_CORS">HTTP access control (CORS)</a></li> + <li><a href="/zh-TW/docs/Web/HTTP">HTTP</a></li> + <li><a href="https://github.com/github/fetch">Fetch polyfill</a></li> + <li><a href="/zh-TW/docs/Web/API/Fetch_API/Basic_concepts">Fetch 基本概念</a></li> +</ul> diff --git a/files/zh-tw/web/api/fetch_api/using_fetch/index.html b/files/zh-tw/web/api/fetch_api/using_fetch/index.html new file mode 100644 index 0000000000..3af949b659 --- /dev/null +++ b/files/zh-tw/web/api/fetch_api/using_fetch/index.html @@ -0,0 +1,379 @@ +--- +title: Using Fetch +slug: Web/API/Fetch_API/Using_Fetch +tags: + - Fetch + - HTTP + - Promise + - Response + - request +translation_of: Web/API/Fetch_API/Using_Fetch +--- +<p>{{DefaultAPISidebar("Fetch API")}}</p> + +<div class="summary"> +<p><a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a> 提供了一種 JavaScript Interface 來操作 HTTP pipeline，比方 request 和 response。同時它也提供了 global 的 {{domxref("GlobalFetch.fetch","fetch()")}} method，使得在網路上非同步地 fetch resources 這件事變得簡單易懂。</p> +</div> + +<p>同樣的功能，以前都是使用 {{domxref("XMLHttpRequest")}}，而 Fetch 作為其替代方案，能更方便地整合在如 {{domxref("ServiceWorker_API", "Service Workers")}} 等相關技術上。此外，Fetch 具備額外的 logical palce，能拿來定義其他和 HTTP 有關的東西，像是 CORS 和 HTTP extensions。</p> + +<p> <code>fetch</code> 和 <code>jQuery.ajax()</code> 有三個主要的差異:</p> + +<ul> + <li><code>fetch()</code> 回傳的 promise <strong>不會 reject HTTP 的 error status</strong>，就算是 HTTP 404 或 500 也一樣。相反地，它會正常地 resolve，並把 <code>ok</code> status 設為 false。會讓它發生 reject 的只有網路錯誤或其他會中斷 request 的情況。</li> + <li><code>fetch</code> <strong>可以接收跨站的 cookies</strong>，你可以用 Fetch 來建立跨站的 session。</li> + <li><code>fetch</code> <strong>不會傳送 cookies</strong>，除非你有設定 credentials 的 <a href="https://wiki.developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters">init option</a>。 (Since <a href="https://github.com/whatwg/fetch/pull/585" rel="nofollow noopener">Aug 25, 2017</a>. The spec changed the default credentials policy to <code>same-origin</code>. Firefox changed since 61.0b13.)</li> +</ul> + +<h2 id="使用_Fetch_發送請求_request">使用 Fetch 發送請求 ( request )</h2> + +<p>用法簡單，如下:</p> + +<pre class="brush: js notranslate">fetch('http://example.com/movies.json') + .then(function(response) { + return response.json(); + }) + .then(function(myJson) { + console.log(myJson); + }); + +</pre> + +<p>這裡要使用 fetch 透過網路取得 json 然後印出在 console，最簡單的方式只需要一個參數就是資料的 URI，fetch 會回傳一個包含 response 的 promise 。</p> + +<p>這個範例使用的 url 只是示意用。</p> + +<p>回傳的 response 需要透過 {{domxref("Body.json","json()")}} (在 {{domxref("Body")}} 可以找到定義, Body 是用 {{domxref("Request")}} 和 {{domxref("Response")}} 實作出來的物件.)</p> + +<div class="note"> +<p><strong>備註</strong>: 其實 Body 還提供了其他類似的功能可以將內容輸成其他類型格式，詳見{{anch("Body")}} </p> +</div> + +<p>Fetch 請求的安全性 <a href="/en-US/docs/Security/CSP/CSP_policy_directives">Content Security Policy</a>(內容安全策略) 是由 header 中的 <code>connect-src</code> directive 所設定 ，並非其他 directive ( 比如：img-src、default-src 等)。</p> + +<h3 id="Request_可用的設定值">Request 可用的設定值</h3> + +<p><code>fetch()</code> 第二個參數是選用的，可以傳送一個 <code>init</code> Object 來設定 request。</p> + +<p>更多可以用的設定值詳見 {{domxref("GlobalFetch.fetch","fetch()")}} </p> + +<pre class="brush: js notranslate">// 來發個 POST Request: + +postData('http://example.com/answer', {answer: 42}) + .then(data => console.log(data)) // JSON from `response.json()` call + .catch(error => console.error(error)) + +function postData(url, data) { + // Default options are marked with * + return fetch(url, { + body: JSON.stringify(data), // must match 'Content-Type' header + cache: 'no-cache', // *default, no-cache, reload, force-cache, only-if-cached + credentials: 'same-origin', // include, same-origin, *omit + headers: { + 'user-agent': 'Mozilla/4.0 MDN Example', + 'content-type': 'application/json' + }, + method: 'POST', // *GET, POST, PUT, DELETE, etc. + mode: 'cors', // no-cors, cors, *same-origin + redirect: 'follow', // manual, *follow, error + referrer: 'no-referrer', // *client, no-referrer + }) + .then(response => response.json()) // 輸出成 json +} +</pre> + +<h3 id="包含憑證Credentials_的_Request_用法">包含憑證(Credentials) 的 Request 用法</h3> + +<p>要讓瀏覽器將 credentials 跟著 request 一起送出, 方式就是在 <code>init</code> object 加上 <code>credentials: 'include'</code> </p> + +<pre class="brush: js notranslate">fetch('https://example.com', { + credentials: 'include' +})</pre> + +<p>如果只想要把 credentials 發送給同源的 URL ，加上<code>credentials: 'same-origin'</code>。</p> + +<pre class="brush: js notranslate">// The calling script is on the origin 'https://example.com' + +fetch('https://example.com', { + credentials: 'same-origin' +})</pre> + +<p>或要確保瀏覽器不會帶著 credentials 請求，可以用 <code>credentials: 'omit'</code> 。</p> + +<pre class="brush: js notranslate">fetch('https://example.com', { + credentials: 'omit' +})</pre> + +<h3 id="上傳JSON資料">上傳JSON資料</h3> + +<p>使用 {{domxref("GlobalFetch.fetch","fetch()")}} 來 POST JSON 格式的資料。</p> + +<pre class="brush: js notranslate">var url = 'https://example.com/profile'; +var data = {username: 'example'}; + +fetch(url, { + method: 'POST', // or 'PUT' + body: JSON.stringify(data), // data can be `string` or {object}! + headers: new Headers({ + 'Content-Type': 'application/json' + }) +}).then(res => res.json()) +.catch(error => console.error('Error:', error)) +.then(response => console.log('Success:', response)); +</pre> + +<h3 id="上傳檔案">上傳檔案</h3> + +<p>上傳檔案可以透過使用HTML <code><input type="file" /></code> input element, {{domxref("FormData.FormData","FormData()")}} 與{{domxref("GlobalFetch.fetch","fetch()")}}.</p> + +<pre class="brush: js notranslate">var formData = new FormData(); +var fileField = document.querySelector("input[type='file']"); + +formData.append('username', 'abc123'); +formData.append('avatar', fileField.files[0]); + +fetch('https://example.com/profile/avatar', { + method: 'PUT', + body: formData +}) +.then(response => response.json()) +.catch(error => console.error('Error:', error)) +.then(response => console.log('Success:', response)); +</pre> + +<h3 id="如何確認fetch是否成功">如何確認fetch是否成功</h3> + +<p>當{{domxref("GlobalFetch.fetch","fetch()")}}遇到CORS或server設定錯誤導致network error時, promise會reject並附上{{jsxref("TypeError")}}的回應, 但在權限或類似問題導致404的常見狀況下, 卻不會導致network error.</p> + +<p>因此, 確認<code>fetch()</code>是否成功的正確方式, 應包含檢查promise resolved, 以及檢查{{domxref("Response.ok")}}的屬性是否為true. 代碼如下例：</p> + +<pre class="brush: js notranslate">fetch('flowers.jpg').then(function(response) { + if(response.ok) { + return response.blob(); + } + throw new Error('Network response was not ok.'); +}).then(function(myBlob) { + var objectURL = URL.createObjectURL(myBlob); + myImage.src = objectURL; +}).catch(function(error) { + console.log('There has been a problem with your fetch operation: ', error.message); +});</pre> + +<h3 id="Supplying_your_own_request_object">Supplying your own request object</h3> + +<p>Instead of passing a path to the resource you want to request into the <code>fetch()</code> call, you can create a request object using the {{domxref("Request.Request","Request()")}} constructor, and pass that in as a <code>fetch()</code> method argument:</p> + +<pre class="brush: js notranslate">var myHeaders = new Headers(); + +var myInit = { method: 'GET', + headers: myHeaders, + mode: 'cors', + cache: 'default' }; + +var myRequest = new Request('flowers.jpg', myInit); + +fetch(myRequest).then(function(response) { + return response.blob(); +}).then(function(myBlob) { + var objectURL = URL.createObjectURL(myBlob); + myImage.src = objectURL; +});</pre> + +<p><code>Request()</code> accepts exactly the same parameters as the <code>fetch()</code> method. You can even pass in an existing request object to create a copy of it:</p> + +<pre class="brush: js notranslate">var anotherRequest = new Request(myRequest, myInit);</pre> + +<p>This is pretty useful, as request and response bodies are one use only. Making a copy like this allows you to make use of the request/response again, while varying the <code>init</code> options if desired. The copy must be made before the body is read, and reading the body in the copy will also mark it as read in the original request.</p> + +<div class="note"> +<p><strong>Note</strong>: There is also a {{domxref("Request.clone","clone()")}} method that creates a copy. Both methods of creating a copy will fail if the body of the original request or response has already been read, but reading the body of a cloned response or request will not cause it to be marked as read in the original.</p> +</div> + +<h2 id="Headers">Headers</h2> + +<p>The {{domxref("Headers")}} interface allows you to create your own headers object via the {{domxref("Headers.Headers","Headers()")}} constructor. A headers object is a simple multi-map of names to values:</p> + +<pre class="brush: js notranslate">var content = "Hello World"; +var myHeaders = new Headers(); +myHeaders.append("Content-Type", "text/plain"); +myHeaders.append("Content-Length", content.length.toString()); +myHeaders.append("X-Custom-Header", "ProcessThisImmediately");</pre> + +<p>The same can be achieved by passing an array of arrays or an object literal to the constructor:</p> + +<pre class="brush: js notranslate">myHeaders = new Headers({ + "Content-Type": "text/plain", + "Content-Length": content.length.toString(), + "X-Custom-Header": "ProcessThisImmediately", +});</pre> + +<p>The contents can be queried and retrieved:</p> + +<pre class="brush: js notranslate">console.log(myHeaders.has("Content-Type")); // true +console.log(myHeaders.has("Set-Cookie")); // false +myHeaders.set("Content-Type", "text/html"); +myHeaders.append("X-Custom-Header", "AnotherValue"); + +console.log(myHeaders.get("Content-Length")); // 11 +console.log(myHeaders.get("X-Custom-Header")); // ["ProcessThisImmediately", "AnotherValue"] + +myHeaders.delete("X-Custom-Header"); +console.log(myHeaders.get("X-Custom-Header")); // [ ]</pre> + +<p>Some of these operations are only useful in {{domxref("ServiceWorker_API","ServiceWorkers")}}, but they provide a much nicer API for manipulating headers.</p> + +<p>All of the Headers methods throw a <code>TypeError</code> if a header name is used that is not a valid HTTP Header name. The mutation operations will throw a <code>TypeError</code> if there is an immutable guard (see below). Otherwise they fail silently. For example:</p> + +<pre class="brush: js notranslate">var myResponse = Response.error(); +try { + myResponse.headers.set("Origin", "http://mybank.com"); +} catch(e) { + console.log("Cannot pretend to be a bank!"); +}</pre> + +<p>A good use case for headers is checking whether the content type is correct before you process it further. For example:</p> + +<pre class="brush: js notranslate">fetch(myRequest).then(function(response) { + var contentType = response.headers.get("content-type"); + if(contentType && contentType.includes("application/json")) { + return response.json(); + } + throw new TypeError("Oops, we haven't got JSON!"); + }) + .then(function(json) { /* process your JSON further */ }) + .catch(function(error) { console.log(error); });</pre> + +<h3 id="Guard">Guard</h3> + +<p>Since headers can be sent in requests and received in responses, and have various limitations about what information can and should be mutable, headers objects have a guard property. This is not exposed to the Web, but it affects which mutation operations are allowed on the headers object.</p> + +<p>Possible guard values are:</p> + +<ul> + <li><code>none</code>: default.</li> + <li><code>request</code>: guard for a headers object obtained from a request ({{domxref("Request.headers")}}).</li> + <li><code>request-no-cors</code>: guard for a headers object obtained from a request created with {{domxref("Request.mode")}} <code>no-cors</code>.</li> + <li><code>response</code>: guard for a Headers obtained from a response ({{domxref("Response.headers")}}).</li> + <li><code>immutable</code>: Mostly used for ServiceWorkers; renders a headers object read-only.</li> +</ul> + +<div class="note"> +<p><strong>Note</strong>: You may not append or set a <code>request</code> guarded Headers’ <code>Content-Length</code> header. Similarly, inserting <code>Set-Cookie</code> into a response header is not allowed: ServiceWorkers are not allowed to set cookies via synthesized responses.</p> +</div> + +<h2 id="Response_objects">Response objects</h2> + +<p>As you have seen above, {{domxref("Response")}} instances are returned when <code>fetch()</code> promises are resolved.</p> + +<p>The most common response properties you'll use are:</p> + +<ul> + <li>{{domxref("Response.status")}} — An integer (default value 200) containing the response status code.</li> + <li>{{domxref("Response.statusText")}} — A string (default value "OK"), which corresponds to the HTTP status code message.</li> + <li>{{domxref("Response.ok")}} — seen in use above, this is a shorthand for checking that status is in the range 200-299 inclusive. This returns a {{domxref("Boolean")}}.</li> +</ul> + +<p>They can also be created programmatically via JavaScript, but this is only really useful in {{domxref("ServiceWorker_API", "ServiceWorkers")}}, when you are providing a custom response to a received request using a {{domxref("FetchEvent.respondWith","respondWith()")}} method:</p> + +<pre class="brush: js notranslate">var myBody = new Blob(); + +addEventListener('fetch', function(event) { // ServiceWorker intercepting a fetch + event.respondWith( + new Response(myBody, { + headers: { "Content-Type" : "text/plain" } + }) + ); +});</pre> + +<p>The {{domxref("Response.Response","Response()")}} constructor takes two optional arguments — a body for the response, and an init object (similar to the one that {{domxref("Request.Request","Request()")}} accepts.)</p> + +<ul> +</ul> + +<div class="note"> +<p><strong>Note</strong>: The static method {{domxref("Response.error","error()")}} simply returns an error response. Similarly, {{domxref("Response.redirect","redirect()")}} returns a response resulting in a redirect to a specified URL. These are also only relevant to Service Workers.</p> +</div> + +<h2 id="Body">Body</h2> + +<p>Both requests and responses may contain body data. A body is an instance of any of the following types:</p> + +<ul> + <li>{{domxref("ArrayBuffer")}}</li> + <li>{{domxref("ArrayBufferView")}} (Uint8Array and friends)</li> + <li>{{domxref("Blob")}}/File</li> + <li>string</li> + <li>{{domxref("URLSearchParams")}}</li> + <li>{{domxref("FormData")}}</li> +</ul> + +<p>The {{domxref("Body")}} mixin defines the following methods to extract a body (implemented by both {{domxref("Request")}} and {{domxref("Response")}}). These all return a promise that is eventually resolved with the actual content.</p> + +<ul> + <li>{{domxref("Body.arrayBuffer","arrayBuffer()")}}</li> + <li>{{domxref("Body.blob","blob()")}}</li> + <li>{{domxref("Body.json","json()")}}</li> + <li>{{domxref("Body.text","text()")}}</li> + <li>{{domxref("Body.formData","formData()")}}</li> +</ul> + +<p>This makes usage of non-textual data much easier than it was with XHR.</p> + +<p>Request bodies can be set by passing body parameters:</p> + +<pre class="brush: js notranslate">var form = new FormData(document.getElementById('login-form')); +fetch("/login", { + method: "POST", + body: form +});</pre> + +<p>Both request and response (and by extension the <code>fetch()</code> function), will try to intelligently determine the content type. A request will also automatically set a <code>Content-Type</code> header if none is set in the dictionary.</p> + +<h2 id="特性偵測">特性偵測</h2> + +<p>想確認是否支持 Fetch API，可透過檢查 {{domxref("Headers")}}、{{domxref("Request")}}、{{domxref("Response")}} 或 {{domxref("GlobalFetch.fetch","fetch()")}} 是否存在 {{domxref("Window")}} 或 {{domxref("Worker")}} 域中。例如：</p> + +<pre class="brush: js notranslate">if (self.fetch) { + // run my fetch request here +} else { + // do something with XMLHttpRequest? +}</pre> + +<h2 id="Polyfill">Polyfill</h2> + +<p>在不支援 Fetch 的瀏覽器, 可改用 <a href="https://github.com/github/fetch">Fetch Polyfill</a> 來重新支持缺少的 fetch 功能。</p> + +<h2 id="技術指標">技術指標</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">技術名稱</th> + <th scope="col">狀態</th> + <th scope="col">說明</th> + </tr> + <tr> + <td>{{SpecName('Fetch')}}</td> + <td>{{Spec2('Fetch')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<div class="bc-data" id="bcd:api.WindowOrWorkerGlobalScope.fetch"> + + +<p>{{Compat("api.WindowOrWorkerGlobalScope.fetch")}}</p> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/ServiceWorker_API">ServiceWorker API</a></li> + <li><a href="/en-US/docs/Web/HTTP/Access_control_CORS">HTTP access control (CORS)</a></li> + <li><a href="/en-US/docs/Web/HTTP">HTTP</a></li> + <li><a href="https://github.com/github/fetch">Fetch polyfill</a></li> + <li><a href="https://github.com/mdn/fetch-examples/">Fetch examples on Github</a></li> +</ul> diff --git a/files/zh-tw/web/api/file/file/index.html b/files/zh-tw/web/api/file/file/index.html new file mode 100644 index 0000000000..1990248f72 --- /dev/null +++ b/files/zh-tw/web/api/file/file/index.html @@ -0,0 +1,112 @@ +--- +title: File.File() +slug: Web/API/File/File +translation_of: Web/API/File/File +--- +<p>{{APIRef("File")}}</p> + +<p><code><strong>File()</strong></code> 建構子建立一個新的 {{domxref("File")}} 物件實例</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">var myFile = new File(bits, name[, options]);</pre> + +<h3 id="參數">參數</h3> + +<dl> + <dt><em>bits</em></dt> + <dd>An {{jsxref("Array")}} of {{jsxref("ArrayBuffer")}}, {{domxref("ArrayBufferView")}}, {{domxref("Blob")}}, or {{domxref("DOMString")}} objects — 或是由這些物件組成的集合。這是以 UTF-8 編碼的檔案內容。</dd> + <dt><em>name</em></dt> + <dd>檔案名稱或檔案的路徑（{{domxref("USVString")}}）。</dd> + <dt><em>options</em> {{optional_inline}}</dt> + <dd>物件選項，包含物件非必要的屬性，以下為可得到的屬性： + <ul> + <li><code>type</code>: 物件的 MIME 類型（{{domxref("DOMString")}} ）將被放進檔案中，預設為 ""（空值）。</li> + <li><code>lastModified</code>: 檔案最後修改時間，格式為毫秒，預設為 {{jsxref("Date.now()")}}.</li> + </ul> + </dd> +</dl> + +<h2 id="範例">範例</h2> + +<pre class="brush: js">var file = new File(["foo"], "foo.txt", { + type: "text/plain", +});</pre> + +<h2 id="規格">規格</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規格</th> + <th scope="col">狀態</th> + <th scope="col">說明</th> + </tr> + <tr> + <td>{{SpecName('File API')}}</td> + <td>{{Spec2('File API')}}</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>Edge</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>13</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop("7")}}</td> + <td>{{CompatNo}}</td> + <td>11.5</td> + <td>10.1</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>4.4.4</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("7")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>6.0</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="看更多">看更多</h2> + +<ul> + <li>{{domxref("FileReader")}}</li> + <li>{{domxref("Blob")}}</li> +</ul> diff --git a/files/zh-tw/web/api/file/filename/index.html b/files/zh-tw/web/api/file/filename/index.html new file mode 100644 index 0000000000..0e6cceb4f3 --- /dev/null +++ b/files/zh-tw/web/api/file/filename/index.html @@ -0,0 +1,32 @@ +--- +title: File.fileName +slug: Web/API/File/fileName +translation_of: Web/API/File/fileName +--- +<p>{{APIRef("File API")}}{{non-standard_header}}</p> + +<p>{{deprecated_header(7.0)}}</p> + +<h2 id="總覽">總覽</h2> + +<p>回傳檔案名稱，基於安全因素，檔案路徑不包含這個屬性。</p> + +<div class="note">這個檔案是廢棄的，使用 {{domxref("File.name")}} 取代。</div> + +<h2 id="語法">語法</h2> + +<pre>var name = instanceOfFile.fileName</pre> + +<h2 id="數值">數值</h2> + +<p>字串</p> + +<h2 id="Specification" name="Specification">格式</h2> + +<p>尚無資料</p> + +<h2 id="看更多">看更多</h2> + +<ul> + <li>{{domxref("File.name")}}</li> +</ul> diff --git a/files/zh-tw/web/api/file/index.html b/files/zh-tw/web/api/file/index.html new file mode 100644 index 0000000000..0dce936ff8 --- /dev/null +++ b/files/zh-tw/web/api/file/index.html @@ -0,0 +1,121 @@ +--- +title: File +slug: Web/API/File +tags: + - API + - File API + - Interface + - Reference + - Web + - 介面 + - 參考 + - 檔案 API + - 檔案API + - 網路 +translation_of: Web/API/File +--- +<div>{{APIRef}}</div> + +<p><strong><code>File</code></strong> 介面提供了檔案的資訊並且允許網頁中的 JavaScript 存取檔案的內容。</p> + +<p><code>File</code> 物件通常是從使用者於 {{HTMLElement("input")}} 元素選擇之檔案所回傳的 {{domxref("FileList")}} 物件當中取得，也可以來自<a href="/zh-TW/docs/Web/Guide/HTML/Drag_and_drop">拖放操作</a>所產生的 {{domxref("DataTransfer")}} 物件之中，或是由 {{domxref("HTMLCanvasElement")}} 物件（元素物件）執行 <code>mozGetAsFile()</code> 方法後回傳。在 Gecko 引擎中，有專屬的程式碼能不需使用者操作即建立 <code>File</code> 物件來表示本地端的任一檔案（請參考 {{anch("Implementation notes")}} 以閱讀更多資訊）。</p> + +<p><code>File</code> 物件是一種特殊的 {{domxref("Blob")}}，且可被用在任何接受 Blob 物件的地方。特別是 {{domxref("FileReader")}}、{{domxref("URL.createObjectURL()")}}、{{domxref("ImageBitmapFactories.createImageBitmap()", "createImageBitmap()")}} 和 {{domxref("XMLHttpRequest", "", "send()")}} 都能夠同樣接受 <code>Blob</code> 以及 <code>File</code>。</p> + +<p>請參考<a href="/docs/Using_files_from_web_applications">在網頁應用程式中使用本地檔案</a>的更多細節與範例。</p> + +<p>{{InheritanceDiagram}}</p> + +<h2 id="建構式">建構式</h2> + +<dl> + <dt>{{domxref("File.File", "File()")}}</dt> + <dd>回傳一個新建構的 <code>File</code> 物件。</dd> +</dl> + +<h2 id="屬性">屬性</h2> + +<dl> + <dt>{{domxref("File.lastModified")}} {{readonlyinline}}</dt> + <dd>回值檔案的最後修改時間，為 UNIX epoch 毫秒（自西元 1970 年一月 1 日零時至今）。</dd> + <dt>{{domxref("File.lastModifiedDate")}} {{readonlyinline}} {{deprecated_inline}} {{gecko_minversion_inline("15.0")}}</dt> + <dd><code>File</code> 物件所代表之檔案的最後修改日期（<code><a href="/docs/Web/JavaScript/Reference/Global_Objects/Date">Date</a></code>）。</dd> + <dt>{{domxref("File.name")}} {{readonlyinline}}</dt> + <dd><code>File</code> 物件所代表之檔案的名稱。</dd> + <dt>{{domxref("File.size")}} {{readonlyinline}}</dt> + <dd>回傳檔案大小。</dd> + <dt>{{domxref("File.webkitRelativePath")}} {{readonlyinline}} {{non-standard_inline}}</dt> + <dd>回傳相對於 {{domxref("File")}} 的網址位置。</dd> + <dt>{{domxref("File.type")}} {{readonlyinline}}</dt> + <dd>回傳檔案的 <a href="/docs/Web/HTTP/Basics_of_HTTP/MIME_types">MIME</a> 類型。</dd> +</dl> + +<p><code>File</code> 實作了 {{domxref("Blob")}}，因此它也有以下可用屬性：</p> + +<dl> + <dt>{{domxref("File.size")}} {{readonlyinline}}</dt> + <dd>回傳檔案大小（單位為位元組）。</dd> + <dt>{{domxref("File.type")}} {{readonlyinline}}</dt> + <dd>回傳檔案的 <a href="/zh-TW/docs/Web/HTTP/Basics_of_HTTP/MIME_types">MIME </a>類型。</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em><code>File</code> 介面沒有定義任何方法，但繼承了 {{domxref("Blob")}} 介面的方法：</em></p> + +<dl> + <dt>{{domxref("Blob.slice()", "Blob.slice([start[, end[, contentType]]])")}}</dt> + <dd> + <p>回傳新的 <code>Blob</code> 物件，包含 <code>Blob</code> 來源之指定位元組範圍的資料。</p> + </dd> +</dl> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">備註</th> + </tr> + <tr> + <td>{{SpecName('File API')}}</td> + <td>{{Spec2('File API')}}</td> + <td>初次定義</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<div> + + +<p>{{Compat("api.File")}}</p> +</div> + +<p> </p> + +<h3 id="實作備註">實作備註</h3> + +<ul> + <li>In Gecko, you can use this API from within chrome code. See <a href="/en-US/docs/Extensions/Using_the_DOM_File_API_in_chrome_code">Using the DOM File API in chrome code</a> for details. To use it from chrome code, JSM and Bootstrap scope, you have to import it using <code><a href="/en-US/docs/Components.utils.importGlobalProperties">Cu.importGlobalProperties</a>(['File']);</code></li> + <li>Starting from Gecko 6.0 {{geckoRelease("6.0")}}, privileged code (such as extensions) can pass an {{interface("nsIFile")}} object to the DOM <code>File</code> constructor to specify the file to reference.</li> + <li>Starting from Gecko 8.0 {{geckoRelease("8.0")}}, you can use <code>new File</code> to create <code>File</code> objects from XPCOM component code instead of having to instantiate the {{interface("nsIDOMFile")}} object directly. The constructor takes, in contrast to {{domxref("Blob")}}, as second argument the filename. The filename can be any String. + <pre class="syntaxbox">new File( + Array parts, + String filename, + BlobPropertyBag properties +);</pre> + </li> + <li>The following non-standard properties and methods were removed in Gecko 7 {{geckoRelease("7.0")}}: {{domxref("File.fileName")}}, {{domxref("File.fileSize")}}, {{domxref("File.getAsBinary()")}}, {{domxref("File.getAsDataURL()")}}, {{domxref("File.getAsText()","File.getAsText(string encoding)")}} ({{bug("661876")}}). Standard properties {{domxref("File.name")}}, {{domxref("Blob.size")}}, and methods on {{domxref("FileReader")}} should be used instead.</li> +</ul> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/docs/Using_files_from_web_applications">在網頁應用程式中使用本地檔案</a></li> + <li>{{domxref("FileReader")}}</li> + <li><a href="/docs/Extensions/Using_the_DOM_File_API_in_chrome_code">Using the DOM File API in chrome code</a> (for privileged code running in Gecko, such as Firefox add-ons)</li> +</ul> diff --git a/files/zh-tw/web/api/file/using_files_from_web_applications/index.html b/files/zh-tw/web/api/file/using_files_from_web_applications/index.html new file mode 100644 index 0000000000..52bd1928b3 --- /dev/null +++ b/files/zh-tw/web/api/file/using_files_from_web_applications/index.html @@ -0,0 +1,411 @@ +--- +title: 在網頁應用程式中使用本地檔案 +slug: Web/API/File/Using_files_from_web_applications +tags: + - 待翻譯 +translation_of: Web/API/File/Using_files_from_web_applications +--- +<p> {{ gecko_minversion_header("1.9.2") }}</p> + +<p>現在可以透過新增至HTML5 DOM的File API讓web內容要求使用者選取本地端的檔案後讀取被選取檔案中的內容。檔案的選取動作可以使用HTML的 <a href="/en/DOM/HTMLInputElement" title="en/DOM/Input"><code>input</code></a> 元素，或是用拖曳檔案（drag and drop）的方式來完成。</p> + +<p>如果你想要使用 DOM 檔案 API 的文件擴展或是其他Chrome 程式碼，你可以參考<a href="/en/Extensions/Using_the_DOM_File_API_in_chrome_code" title="en/Extensions/Using the DOM File API in chrome code">使用DOM檔案API在FireFox外觀代碼中</a>。</p> + +<h2 id="使用HTML選擇本地檔案">使用HTML選擇本地檔案</h2> + +<p>HTML 語法：</p> + +<pre><code><input type="file" id="input"></code></pre> + +<p>File API 可以從 {{ domxref("File") }} 物件中讀取 {{ domxref("FileList") }} ，{{domxref("FileList") }} 內包含使用者所選取的檔案。</p> + +<p>如果使用者只選擇一個檔案，那麼我們只需要考慮第一個檔案物件。</p> + +<p>使用 DOM 獲取選擇的檔案：</p> + +<pre><code>var selectedFile = document.getElementById('input').files[0];</code></pre> + +<p>使用 <a href="http://jquery.com/" title="http://jquery.com/">jQuery</a> 獲取選擇的檔案：</p> + +<pre><code>var selectedFile = $('#input').get(0).files[0]; + +var selectedFile = $('#input')[0].files[0];</code> +</pre> + +<div class="note"> +<p>如果獲取 "files is undefined" 錯誤: 代表未選擇正確的 HTML 元素, 這時忘記 jQuery 回傳符合 DOM 元素的清單. 改使用 DOM 元素呼叫 "files" 方法.</p> +</div> + +<h2 id="使用_change_event_獲取選擇的檔案">使用 change event 獲取選擇的檔案</h2> + +<p>使用File API選擇單一檔案是非常簡單的，如下</p> + +<pre><code><input type="file" id="input" onchange="handleFiles(this.files)"></code> +</pre> + +<p>當使用者選取一個檔案，呼叫 <code>handleFiles()</code> 會得到一個 {{domxref("FileList") }} 的物件。{{domxref("FileList") }} 裡面還會有一個 <code>{{domxref("File")}}</code> 的物件，裡面的東西就是使用者選取的檔案。</p> + +<p>如果你想要讓使用者一次選擇多個檔案，可以在 <code>input</code> 元素中使用 <code>multiple</code> 的屬性：</p> + +<pre><code><input type="file" id="input" multiple="true" onchange="handleFiles(this.files)"></code> + +</pre> + +<p>在上述這個例子中，<span style="line-height: 1.5;">檔案名單</span><span style="line-height: 1.5;">會傳遞到</span><span style="line-height: 1.5;"> </span><code style="font-style: normal; line-height: 1.5;">handleFiles()</code><span style="line-height: 1.5;"> 函數</span>，其中包含了<span style="line-height: 1.5;">使用者選的每個檔案 {{domxref("File")}} </span><span style="line-height: 1.5;">物件</span><span style="line-height: 1.5;">。</span></p> + +<h3 id="使用_EventListener_動態地監聽">使用 EventListener 動態地監聽</h3> + +<p>如果使用了其他的函數庫（<a class="external" href="http://www.jquery.com/" title="http://www.jquery.com/">jQuery</a>），你會需要使用 {{domxref("EventTarget.addEventListener()") }} 去監聽事件，例如：</p> + +<pre class="brush: js">var inputElement = document.getElementById("inputField"); +inputElement.addEventListener("change", handleFiles, false); + +function handleFiles() { + var fileList = this.files; + + /* now you can work with the file list */ +} +</pre> + +<p>在這個例子中，<code>handleFiles() </code>函數找尋檔案清單而非接收參數, 因為這樣增加的 event listeners 不能接受參數.</p> + +<h2 id="獲得選取檔案的資訊">獲得選取檔案的資訊</h2> + +<p>由DOM提供的 {{domxref("FileList") }} 物件代表使用者選取的所有檔案，每個又是 <code>{{domxref("File")}} </code>物件。可以藉由 {{domxref("FileList") }} 的 length 屬性得知使用者選取的檔案數量：</p> + +<pre>var numFiles = files.length; +</pre> + +<p>使用陣列獲取 {{domxref("File")}} 物件：</p> + +<pre>for (var i = 0; i < files.length; i++) { + var file = files[i]; + .. +} +</pre> + +<p>上述的例子顯示獲取在檔案清單裡所有檔案物件的方法。</p> + +<p><font face="Consolas, Liberation Mono, Courier, monospace">{{domxref("File")}} </font>提供三個包含檔案重要訊息的屬性。</p> + +<dl> + <dt><code>name</code></dt> + <dd>唯讀的檔案名稱，並未包含檔案路徑。</dd> + <dt><code>size</code></dt> + <dd>為 64 位元的整數，用以表示檔案的 byte 的長度。</dd> + <dt><code>type</code></dt> + <dd>為唯讀字串。表示檔案的 MIME-type 。若是無法取得檔案的 Mime-type ，則其值會是一個空字串 <code>""</code>。</dd> +</dl> + +<p> </p> + +<h2 id="使用click()_方法隱藏檔案輸入元素">使用click() 方法隱藏檔案輸入元素</h2> + +<p>從 Gecko 2.0 {{ geckoRelease("2.0") }}開始，為了顯示個人化開啟檔案的UI和使用者選擇的檔案可以隱藏 {{ HTMLElement("input") }} 元素和顯示個人化的設計。可以藉由設置CSS 「display:none」 和對 {{ HTMLElement("input") }} 元素呼叫 <code>click()</code> 方法。</p> + +<p>HTML 如下：</p> + +<pre><input type="file" id="fileElem" multiple="true" accept="image/*" style="display:none" onchange="handleFiles(this.files)"> +<a href="#" id="fileSelect">Select some files</a> +</pre> + +<p><code>doClick()</code> 方法:</p> + +<pre>var fileSelect = document.getElementById("fileSelect"), + fileElem = document.getElementById("fileElem"); + +fileSelect.addEventListener("click", function (e) { + if (fileElem) { + fileElem.click(); + } + e.preventDefault(); // prevent navigation to "#" +}, false); +</pre> + +<p>很明顯的，可以使用CSS來設計新的上傳檔案的按鈕。</p> + +<h2 id="使用拖放選取檔案">使用拖放選取檔案</h2> + +<p>使用者可以使用拖放來選取檔案，首先要設置放的區域，確定文件可以接收放的檔案，方法如下：</p> + +<pre class="brush: js">var dropbox; + +dropbox = document.getElementById("dropbox"); +dropbox.addEventListener("dragenter", dragenter, false); +dropbox.addEventListener("dragover", dragover, false); +dropbox.addEventListener("drop", drop, false); +</pre> + +<p>在這個範例中，我們將 ID "dropbox" 設為放的區域，這是由於我們監聽了 <code>dragenter <font face="Open Sans, Arial, sans-serif">、</font></code><code>dragover </code>和 <code>drop</code>事件<font face="Consolas, Liberation Mono, Courier, monospace">。</font></p> + +<p>我們甚至不需要處理 <code>dragenter <font face="Open Sans, Arial, sans-serif">和 </font></code><code>dragover</code>事件，所以這些函數很簡單。他們阻止了事件的傳播和預設事件的發生：</p> + +<pre class="brush: js">function dragenter(e) { + e.stopPropagation(); + e.preventDefault(); +} + +function dragover(e) { + e.stopPropagation(); + e.preventDefault(); +} +</pre> + +<p>神奇的 <code>drop()</code> 函數:</p> + +<pre class="brush: js">function drop(e) { + e.stopPropagation(); + e.preventDefault(); + + var dt = e.dataTransfer; + var files = dt.files; + + handleFiles(files); +} +</pre> + +<p><code><font face="Open Sans, Arial, sans-serif">這邊我們用 </font>dataTransfer </code>來獲取檔案清單, 並傳遞給 <code>handleFiles()</code>.。 我們可以發現，不論使用拖放或是其他取得檔案，處理檔案的方式都是相同。</p> + +<dl> +</dl> + +<h2 id="範例：顯示選取的圖片">範例：顯示選取的圖片</h2> + +<p>假設要開發一個分享照片的網站，想使用 HTML5 來讓使用者在上傳圖片前預覽縮圖。簡單來說就是像先前討論地一樣建立 input 元素或是 drop 區域，接著再呼叫類似 <code>handleFiles()</code> 的函數。</p> + +<pre class="brush: js">function handleFiles(files) { + for (var i = 0; i < files.length; i++) { + var file = files[i]; + var imageType = /image.*/; + + if (!file.type.match(imageType)) { + continue; + } + + var img = document.createElement("img"); + img.classList.add("obj"); + img.file = file; + preview.appendChild(img); + + var reader = new FileReader(); + reader.onload = (function(aImg) { return function(e) { aImg.src = e.target.result; }; })(img); + reader.readAsDataURL(file); + } +} +</pre> + +<p>這邊迴圈處理了使用者選取的每個檔案並檢查每個檔案的類型是不是圖檔(藉由使用正規表達式檢查是否符合字串 "image.*")。每一個是圖片的檔案，我們創建一個 <code>img</code> 元素。CSS 被使用來美化外框、陰影、還有設定圖片的尺寸，所以那些並不需要在這邊寫入。</p> + +<p>為了使圖片可以在DOM裡面更容易被找到，所以每個圖片都有設定CSS class “obj”。 我們也在每個圖檔標記 <code>file</code> 屬性以辨認 <code><a href="/en/DOM/File" title="en/DOM/File">File</a></code>；這使我們更容易取得真正要上傳的圖檔。最後我們使用{{ domxref("Node.appendChild()") }} 在文件中增加縮圖的元素。</p> + +<p><a href="/en/DOM/FileReader" title="en/DOM/FileReader"><code>FileReader</code></a> 處理要非同步讀取的圖檔並跟 <code>img</code> 元素連接。在創建 <code>FileReader</code> 物件後，我們設置了 <code>onload </code>並 呼叫 <code>readAsDataURL()</code> 在背景呼叫讀取的程序。當所有圖檔都被讀取時，他們被轉換為傳到 <code>onload callback <font face="Open Sans, Arial, sans-serif">的</font></code><code> data</code> URL。 這個範例簡易的設置<code>img</code> 元素的 <code>src</code> 屬性來讀取圖檔並在螢幕上顯示。</p> + +<h2 id="使用_object_URLs">使用 object URLs</h2> + +<p>Gecko 2.0 {{ geckoRelease("2.0") }} 支援 DOM 的{{ domxref("window.URL.createObjectURL()") }} 和 {{ domxref("window.URL.revokeObjectURL()") }} 方法。可以藉由這些方法創建表示任何為 DOM <a href="/en/DOM/File" title="en/DOM/File"><code>File</code></a> 物件的 data URL 字串，包含了使用者電腦上的檔案。</p> + +<p>可以使 <a href="/en/DOM/File" title="en/DOM/File"><code>File</code></a> 物件作為 HTML 元素 URL 的參考，創建 object URL 的方法：</p> + +<pre>var objectURL = window.URL.createObjectURL(fileObj); +</pre> + +<p>object URL 為表示 <a href="/en/DOM/File" title="en/DOM/File"><code>File</code></a> 物件的字串。即使已經對相同檔案創建了 object URL，每次呼叫 {{ domxref("window.URL.createObjectURL()") }}，就會創建一個 object URL。當文檔卸載時他們將會被自動釋放，如果要動態地使用，需要呼叫 {{ domxref("window.URL.revokeObjectURL()") }} 釋放：</p> + +<pre>window.URL.revokeObjectURL(objectURL);</pre> + +<h2 id="範例：使用_object_URLs_顯示圖片">範例：使用 object URLs 顯示圖片</h2> + +<p>{{ geckoRelease("2.0") }}這個範例使用 object URLs 顯示圖像縮圖。此外也顯示了其他包含檔案名稱和檔案大小的訊息。<a href="/samples/domref/file-click-demo.html" title="https://developer.mozilla.org/samples/domref/file-click-demo.html">線上範例</a> (註:瀏覽器版本要求 11/22 之後的火狐版本)。</p> + +<div class="note"><strong>註: </strong>這個 API 在較早的 Firefox 4 betas 存在但是 11/22 號後的版本有改變, 所以確定瀏覽器在最新的版本!</div> + +<p>HTML：</p> + +<pre class="brush: html"><input type="file" id="fileElem" multiple accept="image/*" style="display:none" onchange="handleFiles(this.files)"> +<a href="#" id="fileSelect">Select some files</a> +<div id="fileList"> + <p>No files selected!</p> +</div> +</pre> + +<p>This establishes our file {{ HTMLElement("input") }} element, as well as a link that invokes the file picker, since we keep the file input hidden to prevent that less-than-attractive UI from being displayed. This is explained above in the section {{ anch("Using hidden file input elements using the click() method") }}, as is the <code>doClick()</code> method that invokes the file picker.</p> + +<p>The <code>handleFiles()</code> method follows:</p> + +<pre class="brush: js">var fileSelect = document.getElementById("fileSelect"), + fileElem = document.getElementById("fileElem"), + fileList = document.getElementById("fileList"); + +fileSelect.addEventListener("click", function (e) { + if (fileElem) { + fileElem.click(); + } + e.preventDefault(); // prevent navigation to "#" +}, false); + +function handleFiles(files) { + if (!files.length) { + fileList.innerHTML = "<p>No files selected!</p>"; + } + else { + var list = document.createElement("ul"); + for (var i = 0; i < files.length; i++) { + var li = document.createElement("li"); + list.appendChild(li); + + var img = document.createElement("img"); + img.src = window.URL.createObjectURL(files[i]); + img.height = 60; + img.onload = function () { + window.URL.revokeObjectURL(this.src); + } + li.appendChild(img); + + var info = document.createElement("span"); + info.innerHTML = files[i].name + ": " + files[i].size + " bytes"; + li.appendChild(info); + } + fileList.appendChild(list); + } +} +</pre> + +<p>This starts by fetching the URL of the {{ HTMLElement("div") }} with the ID "fileList". This is the block into which we'll insert out file list, including thumbmails.</p> + +<p>If the {{ domxref("FileList") }} object passed to <code>handleFiles()</code> is <code>null</code>, we simply set the inner HTML of the block to display "No files selected!". Otherwise, we start building our file list, as follows:</p> + +<ol> + <li>A new unordered list ({{ HTMLElement("ul") }} element is created.</li> + <li>The new list element is inserted into the {{ HTMLElement("div") }} block by calling its {{ domxref("element.appendChild()") }} method.</li> + <li>For each {{ domxref("File") }} in the {{ domxref("FileList") }} represented by <code>files</code>: + <ol> + <li>Create a new list item ({{ HTMLElement("li") }}) element and insert it into the list.</li> + <li>Create a new image ({{ HTMLElement("img") }}) element.</li> + <li>Set the image's source to a new object URL representing the file, using {{ domxref("window.URL.createObjectURL()") }} to create the blob URL.</li> + <li>Set the image's height to 60 pixels.</li> + <li>Set up the image's load event handler to release the object URL, since it's no longer needed once the image has been loaded. This is done by calling the {{ domxref("window.URL.revokeObjectURL()") }} method, passing in the object URL string as specified by <code>img.src</code>.</li> + <li>Append the new list item to the list.</li> + </ol> + </li> +</ol> + +<h2 id="範例：上傳檔案">範例：上傳檔案</h2> + +<p>接下來這個範例顯示如何非同步的上傳檔案到伺服器。</p> + +<h3 id="新增上傳的工作">新增上傳的工作</h3> + +<p>接續先前創建縮圖的範例，將每個縮圖都設置 CSS class “obj”， 這使得我們可以很容易地使用{{ domxref("Document.querySelectorAll()") }} 選擇使用者要上傳的圖檔，例如：</p> + +<pre class="brush: js">function sendFiles() { + var imgs = document.querySelectorAll(".obj"); + + for (var i = 0; i < imgs.length; i++) { + new FileUpload(imgs[i], imgs[i].file); + } +} +</pre> + +<p>第二行創建了 <code>imgs </code>陣列，存放著所有文件中 CSS class 為 “obj” 的 Node。在這個範例中，我們使用這個來創建縮圖。Once we have that list, it's trivial to go through the list, creating a new <code>FileUpload</code> instance for each. Each of these handles uploading the corresponding file.</p> + +<h3 id="處理上傳檔案的程序">處理上傳檔案的程序</h3> + +<p><code>FileUpload</code> 函數接受圖檔和檔案.</p> + +<pre class="brush: js">function FileUpload(img, file) { + var reader = new FileReader(); + this.ctrl = createThrobber(img); + var xhr = new XMLHttpRequest(); + this.xhr = xhr; + + var self = this; + this.xhr.upload.addEventListener("progress", function(e) { + if (e.lengthComputable) { + var percentage = Math.round((e.loaded * 100) / e.total); + self.ctrl.update(percentage); + } + }, false); + + xhr.upload.addEventListener("load", function(e){ + self.ctrl.update(100); + var canvas = self.ctrl.ctx.canvas; + canvas.parentNode.removeChild(canvas); + }, false); + xhr.open("POST", "http://demos.hacks.mozilla.org/paul/demos/resources/webservices/devnull.php"); + xhr.overrideMimeType('text/plain; charset=x-user-defined-binary'); + reader.onload = function(evt) { + xhr.sendAsBinary(evt.target.result); + }; + reader.readAsBinaryString(file); +} +</pre> + +<p><code>FileUpload()</code> 函數創建被用來顯示上傳進度的 throbber，接著創建 {{domxref("XMLHttpRequest")}} 上傳檔案.</p> + +<p>傳輸資料前的幾個準備工作:</p> + +<ol> + <li>The <code>XMLHttpRequest</code>'s upload "progress" listener is set to update the throbber with new percentage information, so that as the upload progresses, the throbber will be updated based on the latest information.</li> + <li>The <code>XMLHttpRequest</code>'s upload "load" event handler is set to update the throbber with 100% as the progress information (to ensure the progress indicator actually reaches 100%, in case of granularity quirks during the process). It then removes the throbber, since it's no longer needed. This causes the throbber to disappear once the upload is complete.</li> + <li>The request to upload the image file is opened by calling <code>XMLHttpRequest</code>'s <code>open()</code> method to start generating a POST request.</li> + <li>The MIME type for the upload is set by calling the <code>XMLHttpRequest</code> function <code>overrideMimeType()</code>. In this case, we're using a generic MIME type; you may or may not need to set the MIME type at all, depending on your use case.</li> + <li>The <code>FileReader</code> object is used to convert the file to a binary string.</li> + <li>Finally, when the content is loaded the <code>XMLHttpRequest</code> function <code>sendAsBinary()</code> is called to upload the file's content.</li> +</ol> + +<div class="note"> +<p><strong>註:</strong> 範例中非標準的 <code>sendAsBinary</code> 方法已經在 Gecko 31 {{ geckoRelease(31) }} 廢棄且很快將會被移除。可以改使用標準的 <code>send(Blob data)。</code></p> +</div> + +<h3 id="非同步處理上傳檔案的程序">非同步處理上傳檔案的程序</h3> + +<pre class="brush: js">function fileUpload(file) { + // Please report improvements to: marco.buratto at tiscali.it + + var fileName = file.name, + fileSize = file.size, + fileData = file.getAsBinary(), // works on TEXT data ONLY. + boundary = "xxxxxxxxx", + uri = "serverLogic.php", + xhr = new XMLHttpRequest(); + + xhr.open("POST", uri, true); + xhr.setRequestHeader("Content-Type", "multipart/form-data, boundary="+boundary); // simulate a file MIME POST request. + xhr.setRequestHeader("Content-Length", fileSize); + + xhr.onreadystatechange = function() { + if (xhr.readyState == 4) { + if ((xhr.status >= 200 && xhr.status <= 200) || xhr.status == 304) { + + if (xhr.responseText != "") { + alert(xhr.responseText); // display response. + } + } + } + } + + var body = "--" + boundary + "\r\n"; + body += "Content-Disposition: form-data; name='fileId'; filename='" + fileName + "'\r\n"; + body += "Content-Type: application/octet-stream\r\n\r\n"; + body += fileData + "\r\n"; + body += "--" + boundary + "--"; + + xhr.send(body); + return true; +} +</pre> + +<p><em>使用二進制數據時，這些程式碼還需要修改。</em></p> + +<h2 id="你也可以參考這些文章">你也可以參考這些文章</h2> + +<ul> + <li><code>{{domxref("File")}}</code></li> + <li><font face="Consolas, Liberation Mono, Courier, monospace">{{domxref("FileList")}} </font></li> + <li><font face="Consolas, Liberation Mono, Courier, monospace">{{domxref("FileReader") }} </font></li> + <li><a href="/en/DOM/XMLHttpRequest/Using_XMLHttpRequest" title="En/Using XMLHttpRequest">Using XMLHttpRequest</a></li> + <li><a href="/en/Extensions/Using_the_DOM_File_API_in_chrome_code" title="en/Extensions/Using the DOM File API in chrome code">Using the DOM File API in chrome code</a></li> + <li><code>{{domxref("XMLHttpRequest")}}</code></li> +</ul> + +<p>{{ HTML5ArticleTOC() }}</p> diff --git a/files/zh-tw/web/api/file_handle_api/index.html b/files/zh-tw/web/api/file_handle_api/index.html new file mode 100644 index 0000000000..bd603fe78a --- /dev/null +++ b/files/zh-tw/web/api/file_handle_api/index.html @@ -0,0 +1,233 @@ +--- +title: FileHandle API +slug: Web/API/File_Handle_API +translation_of: Web/API/File_Handle_API +--- +<p>FileHandle API 可操作檔案，例如建立檔案、修改檔案內容 (不同於 <a href="https://developer.mozilla.org/en-US/docs/DOM/File" title="DOM/File">File</a> API)。而正在編輯中的部分，將使用回合制的鎖定機制，以避免發生競態 (Race) 問題。</p> +<h2 id="API">API</h2> +<h3 id="建立_FileHandle">建立 FileHandle</h3> +<p>若要建立 FileHandle 物件，則需要 <a href="https://developer.mozilla.org/en-US/docs/IndexedDB/IDBFactory#open" title="IndexedDB/IDBFactory#open">IndexedDB Database</a>。</p> +<div style="overflow: hidden;"> + <pre class="brush: js">var idbreq = indexedDB.open("MyTestDatabase"); + +idbreq.onsuccess = function(){ + var db = idbreq.result; + var handleReq = db.mozCreateFileHandle("test.bin", "binary"); + + handleReq.onsuccess = function(){ + var handle = handleReq.result; + console.log('handle', handle); + }; +}; +</pre> +</div> +<p><code>mozCreateFileHandle() </code><code>共使用 </code>2<code> 組參數</code> (Argument)：1 組名稱與 1 組檔案類別 (Optional type)。但這 2 組<code>參</code>數均只屬於敘述性<code>參</code>數，不會用於資料庫。舉例來說，名稱可能是空白字串，而且不需為專屬字串。所以 API 根本不會注意這些參數值。</p> +<p>另請注意，上列程式碼僅會建立「暫時性檔案」，亦即當你保留 FileHandle 物件時，該檔案才會存在。如果你要在重新整理頁面/重新啟動 App 之後，仍能保留檔案，則必須將 Handle 儲存於更永久性的位置 (如資料庫本身之內) 中。</p> +<pre class="brush: js">var transaction = db.transaction(["test"], "readwrite"); +var objectStore = transaction.objectStore("test"); +objectStore.add(myFile, myKey).onsuccess = function(event) { + // The file is now referenced from database too. +} +</pre> +<h3 id="FileHandle_介面">FileHandle 介面</h3> +<pre>interface FileHandle +{ + LockedFile open(optional DOMString mode); + DOMRequest getFile() + readonly attribute DOMString name; + readonly attribute DOMString type; + attribute Function? onabort; + attribute Function? onerror; +};</pre> +<dl> + <dt> + open([mode="readonly"])</dt> + <dd> + 可回傳 <a href="#LockedFile_interface">LockedFile</a>。<code>mode</code> 可為「<code>readonly」或「</code><code>readwrite」。</code></dd> + <dt> + getFile()</dt> + <dd> + 針對檔案而回傳 <a href="/en-US/docs/DOM/DOMRequest" title="/en-US/docs/DOM/DOMRequest">DOMRequest</a>。若成功，就會收到以 <a href="https://developer.mozilla.org/en-US/docs/DOM/File" title="DOM/File">File</a> 物件形式呈現的唯讀「snapshot」檔案內容 (可用於任何接受 <a href="https://developer.mozilla.org/en-US/docs/DOM/Blob" title="DOM/Blob">Blob</a> 的地方，如 <a href="https://developer.mozilla.org/en-US/docs/DOM/FileReader" title="DOM/FileReader">FileReader</a> 或 <a href="https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest" title="DOM/XMLHttpRequest">XMLHttpRequest</a> 等)。 + <pre class="brush: js">myFile.getFile().onsuccess = function(event) { + var file = event.target.result; + var transcation = myDatabase.transaction(["snapshots"], "readwrite"); + var objectStore = transaction.objectStore("snapshots"); + objectStore.add(file, snapshotKey).onsuccess = function(event) { + // A new readonly copy of the file has been created. + } +} +</pre> + </dd> + <dt> + name</dt> + <dd> + 檔案名稱。</dd> + <dt> + type</dt> + <dd> + 代表 content-type。</dd> + <dt> + abort event</dt> + <dd> + 放棄已鎖定的檔案，就會發生此事件。</dd> + <dt> + error event</dt> + <dd> + 任何內部錯誤，都會發生此事件。</dd> +</dl> +<h3 id="LockedFile_介面">LockedFile 介面</h3> +<pre>interface LockedFile +{ + readonly attribute FileHandle fileHandle; + readonly attribute DOMString mode; + readonly attribute boolean active; + attribute any? location; + FileRequest getMetadata(optional FileMetadataParameters parameters); + FileRequest readAsArrayBuffer(unsigned long long size); + FileRequest readAsText(unsigned long long size, optional DOMString encoding); + FileRequest write(DOMString or ArrayBuffer or Blob value); + FileRequest append(DOMString or ArrayBuffer or Blob value); + FileRequest truncate(optional unsigned long long size); + FileRequest flush(); + void abort(); + attribute Function? oncomplete; + attribute Function? onabort; + attribute Function? onerror; +};</pre> +<dl> + <dt> + fileHandle</dt> + <dd> + 來自於解鎖的 FileHandle 物件。</dd> + <dt> + mode</dt> + <dd> + <code>「readonly」或「</code><code>readwrite」。</code></dd> + <dt> + active</dt> + <dd> + 一旦建立之後，就隨即啟動 LockedFile。此 LockedFile 是「可寫入存取 (Write access) 實際底層檔案」的唯一物件。LockedFile 上的作業，均於 <a href="http://en.wikipedia.org/wiki/Isolation_%28database_systems%29" title="http://en.wikipedia.org/wiki/Isolation_%28database_systems%29">isolation</a> 之中執行；也就是說，只要啟動了 LockedFile，則此 LockedFile 的所有作業都一定會在底層檔案上依序執行，而不會與其他 LockedFiles 的作業交錯執行。</dd> + <dd> + 若停用了 LockedFile，則只要在同樣的 LockedFile 上執行讀/寫作業，都會丟出錯誤訊息。</dd> +</dl> +<dl> + <dt> + location</dt> + <dd> + 檔案中的位置 (Offset)。每次讀/寫作業之後，此數值均將自動變更。讀寫作業均從該 location 開始，而 null 代表檔案末端。</dd> + <dt> + getMetadata(parameters)</dt> + <dd> + 針對後設資料 (Metadata) 而回傳 <a href="https://developer.mozilla.org/en-US/docs/WebAPI/FileHandle_API#FileRequest_interface" title="WebAPI/FileHandle_API#FileRequest_interface">FileRequest</a>。此<code>參</code>數亦屬於物件，其中將參數名稱作為物件鍵值，布林值作為數值，進而非同步檢索既有的屬性。無數值則代表 <code>true</code>。目前僅有 <code>size</code> 與 <code>lastModified</code> 為可能的參數。</dd> + <dt> + readAsArrayBuffer(size)</dt> + <dd> + 針對既有<code> size </code>的 <a href="https://developer.mozilla.org/en-US/docs/JavaScript/Typed_arrays/ArrayBuffer" title="JavaScript/Typed_arrays/ArrayBuffer">ArrayBuffer</a>，回傳 <a href="https://developer.mozilla.org/en-US/docs/WebAPI/FileHandle_API#FileRequest_interface" title="WebAPI/FileHandle_API#FileRequest_interface">FileRequest</a>。此作業均從 <code>location</code> 開始，另根據讀取位元組的數目，移動 <code>location</code>。</dd> + <dt> + readAsText(size [, encoding])</dt> + <dd> + 針對既有 <code>size</code> 的字串，以既定的<code> encoding</code> 回傳 <a href="/en-US/docs/WebAPI/FileHandle_API#FileRequest_interface" title="WebAPI/FileHandle_API#FileRequest_interface">FileRequest</a>。此作業均從 <code>location</code> 開始，另根據讀取位元組的數目，移動 <code>location</code>。<a href="https://developer.mozilla.org/en-US/docs/DOM/FileReader" title="DOM/FileReader">FileReader</a> API 中的對等函式，也以相同方式運作。 + <pre class="brush: js">var lockedFile = myFile.open(); +var request = lockedFile.readAsText(3); +request.onsuccess = function(event) { + var text = request.result; + // 3 characters have been read. +} +</pre> + </dd> + <dt> + write(value)</dt> + <dd> + 針對成功/失敗的寫入作業，回傳 <a href="/en-US/docs/WebAPI/FileHandle_API#FileRequest_interface" title="WebAPI/FileHandle_API#FileRequest_interface">FileRequest</a>。寫入作業將從 <code>location</code> 開始，另根據寫入位元組的數目，移動位置。 + <pre class="brush: js">var lockedFile = myFile.open("readwrite"); +var request = lockedFile.write("foo"); +request.onsuccess = function(event) { + // The string "foo" has been written. +} +</pre> + </dd> + <dt> + append(value)</dt> + <dd> + 針對成功/失敗的附加 (Append) 作業，回傳 <a href="https://developer.mozilla.org/en-US/docs/WebAPI/FileHandle_API#FileRequest_interface" title="WebAPI/FileHandle_API#FileRequest_interface">FileRequest</a>。不論 <code>location</code> 為何，該數值均附加於檔案末端。在附加資料完畢後，<code>location</code> 隨即設定為 <code>null</code>。</dd> + <dt> + truncate([size])</dt> + <dd> + 針對成功/失敗的截斷 (Truncate) 作業，回傳 <a href="/en-US/docs/WebAPI/FileHandle_API#FileRequest_interface" title="WebAPI/FileHandle_API#FileRequest_interface">FileRequest。</a></dd> + <dd> + 如果是以單一<code>參</code>數呼叫該函式，則截斷成功之後，則<strong>不論</strong><code> location</code> 為何，檔案將剩下第一個 <code>size</code> 的位元組。</dd> + <dd> + 若沒有用任何<code>參</code>數呼叫該函式，則檔案將剩下 <code>location</code> 的第一個位元組。</dd> + <dt> + flush()</dt> + <dd> + 強制移轉緩衝過的資料至磁碟上，作業成功之後將回傳 FileRequest。此時即便 App 當機或非刻意中止，都能確保資料已經位於磁碟上了。</dd> + <dt> + abort()</dt> + <dd> + 停用 LockedFile 並取消全部尚未執行的作業。</dd> + <dt> + complete, abort, error events</dt> +</dl> +<h3 id="FileRequest_介面">FileRequest 介面</h3> +<p>此類型的物件，均是由 LockedFile 介面的所有非同步作業所回傳。此介面繼承了 <a href="https://developer.mozilla.org/en-US/docs/DOM/DOMRequest" title="DOM/DOMRequest">DOMRequest</a> 並類似 <a href="https://developer.mozilla.org/en-US/docs/IndexedDB/IDBRequest" title="IndexedDB/IDBRequest">IDBRequest</a>，同時還擁有 <code>onprogress </code><code>事件。在成功之後，則可透過</code> <code>result </code><code>屬性而取得必要檔案作業的結果。</code></p> +<pre>interface FileRequest : DOMRequest +{ + readonly attribute LockedFile lockedFile; + attribute Function? onprogress; +};</pre> +<dl> + <dt> + </dt> +</dl> +<h2 id="說明">說明</h2> +<h3 id="API_與_FileWriter_的差異？">API 與 FileWriter 的差異？</h3> +<p><a href="http://dev.w3.org/2009/dap/file-system/file-writer.html" title="http://dev.w3.org/2009/dap/file-system/file-writer.html">FileWriter 規格</a>定義了 FileWriter，也就是用以呈現「可編輯的檔案」的物件。<a href="http://lists.w3.org/Archives/Public/public-webapps/2012JanMar/0886.html" title="http://lists.w3.org/Archives/Public/public-webapps/2012JanMar/0886.html">Public-webapps 討論串</a>則下了結論：若單一檔案同時寫入不同的實體 (Entity)，將導致 API 成效不彰。最後就是 FileHandle API 應具備自己的 LockedFile 與交易機制。</p> +<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>{{CompatNo}}</td> + <td>15</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</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>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatNo}}</td> + <td>15</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> + </table> +</div> +<p> </p> diff --git a/files/zh-tw/web/api/filelist/index.html b/files/zh-tw/web/api/filelist/index.html new file mode 100644 index 0000000000..56c2f02235 --- /dev/null +++ b/files/zh-tw/web/api/filelist/index.html @@ -0,0 +1,149 @@ +--- +title: FileList +slug: Web/API/FileList +translation_of: Web/API/FileList +--- +<div>{{APIRef("File API")}}{{gecko_minversion_header("1.9")}}</div> + +<p><code>FileList</code> 型別物件通常來自 HTML {{HTMLElement("input")}} 元素 {{domxref("Document_Object_Model", "DOM")}} 物件的 <code>files</code> 屬性（{{Glossary("property/JavaScript", "property")}}）。你可以操作 <code>FileList</code> 物件來存取使用者透過 <code><input type="file"></code> 元素所選取的檔案，或由拖放操作所產生的檔案（請參考 {{domxref("DataTransfer")}} 物件的更多使用細節）。</p> + +<div class="note"> +<p><strong>註：</strong>在 {{Gecko("1.9.2")}} 之前，{{HTMLElement("input")}} 元素只支援一次選取一個檔案，這代表了 <code>FileList</code> 只能夠包含一個 <code>File</code> 物件。從 {{Gecko("1.9.2")}} 開始，假如 <code><input></code> 元素的 <code>multiple</code> 屬性（attribute）為 true，則 FileList 就可能會包含多個檔案。</p> +</div> + +<h2 id="Using_the_file_list" name="Using_the_file_list">使用 FileList</h2> + +<p>所有 <code><input></code> 元素節點的 {{domxref("Document_Object_Model", "DOM")}} 物件都擁有 <code>files</code> 屬性（{{Glossary("property/JavaScript", "property")}}），此屬性即為 <code>FileList</code>，是一個可藉此存取使用者選取之檔案的類陣列物件。以下範例展示了一個 <code>type</code> 屬性（{{Glossary("attribute")}}）值為 <code>file</code> 的 HTML <code><input></code> 元素：</p> + +<pre class="brush: html"><input id="fileItem" type="file"> +</pre> + +<p>下面範例演示了如何取得 <code><input></code> 元素節點中所包含的第一個 {{domxref("File")}} 型別物件：</p> + +<pre class="brush: js">var file = document.getElementById('fileItem').files[0]; +</pre> + +<h2 id="Method_overview" name="Method_overview">方法概觀</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td><code>File <a href="#item ()">item</a>(index);</code></td> + </tr> + </tbody> +</table> + +<h2 id="Attributes" name="Attributes">屬性</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td class="header">屬性名稱</td> + <td class="header">型別</td> + <td class="header">描述</td> + </tr> + <tr> + <td><code>length</code></td> + <td><code>integer</code></td> + <td>表示 <code>FileList</code> 物件中的檔案數量，唯讀。</td> + </tr> + </tbody> +</table> + +<h2 id="Methods" name="Methods">方法</h2> + +<h3 id="item()" name="item()">item()</h3> + +<p>回傳 <code>FileList</code> 中指定索引的 {{domxref("File")}} 物件。</p> + +<pre class="brush: js">File item( + index +); +</pre> + +<h6 id="Parameters" name="Parameters">參數</h6> + +<dl> + <dt><code>index</code></dt> + <dd>要取得的檔案之索引（起始於零）。</dd> +</dl> + +<h6 id="Return_value" name="Return_value">回傳值</h6> + +<p>要求的 {{domxref("File")}} 物件。</p> + +<h2 id="Example" name="Example">範例</h2> + +<p>此範例演示了迭代所有之使用者於 <code><input></code> 元素選取的檔案：</p> + +<pre class="brush:js">// fileInput is an HTML input element: <input type="file" id="myfileinput" multiple> +var fileInput = document.getElementById("myfileinput"); + +// files is a FileList object (similar to NodeList) +var files = fileInput.files; +var file; + +// loop through files +for (var i = 0; i < files.length; i++) { + + // get item + file = files.item(i); + //or + file = files[i]; + + alert(file.name); +} +</pre> + +<p>以下是更完整的範例：</p> + +<pre class="brush:html"><!DOCTYPE HTML> +<html> +<head> +</head> +<body> +<!--multiple is set to allow multiple files to be selected--> + +<input id="myfiles" multiple type="file"> + +</body> + +<script> + +var pullfiles=function(){ + // love the query selector + var fileInput = document.querySelector("#myfiles"); + var files = fileInput.files; + // cache files.length + var fl = files.length; + var i = 0; + + while ( i < fl) { + // localize file var in the loop + var file = files[i]; + alert(file.name); + i++; + } +} + +// set the input element onchange to call pullfiles +document.querySelector("#myfiles").onchange=pullfiles; + +//a.t +</script> + +</html></pre> + +<h2 id="Specification" name="Specification">規範</h2> + +<ul> + <li><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/number-state.html#concept-input-type-file-selected" title="http://www.whatwg.org/specs/web-apps/current-work/multipage/number-state.html#concept-input-type-file-selected">File upload state</a> (HTML5 working draft)</li> +</ul> + +<h2 id="See_also" name="See_also">參見</h2> + +<ul> + <li><a href="/zh-TW/docs/Using_files_from_web_applications">在網頁應用程式中使用本地檔案</a></li> + <li>{{domxref("File")}}</li> + <li>{{domxref("FileReader")}}</li> +</ul> diff --git a/files/zh-tw/web/api/filereader/error/index.html b/files/zh-tw/web/api/filereader/error/index.html new file mode 100644 index 0000000000..572509db9e --- /dev/null +++ b/files/zh-tw/web/api/filereader/error/index.html @@ -0,0 +1,102 @@ +--- +title: FileReader.error +slug: Web/API/FileReader/error +translation_of: Web/API/FileReader/error +--- +<div>{{APIRef("File API")}}</div> + +<h2 id="總覽">總覽</h2> + +<p>回傳讀取檔案時發生的錯誤。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">var <var>error</var> = <em>instanceOfFileReader</em>.error +</pre> + +<h2 id="Value">Value</h2> + +<p>A {{domxref("DOMError")}}</p> + +<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("File API", "#FileReader-interface", "FileReader")}}</td> + <td>{{Spec2("File API")}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Firefox (Gecko)</th> + <th>Chrome</th> + <th>Edge</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatGeckoDesktop("1.9.2")}}<sup>[1]</sup></td> + <td>7</td> + <td>{{CompatVersionUnknown}}</td> + <td>10<sup>[2]</sup></td> + <td>12.02<sup>[3]</sup></td> + <td>6.0.2</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Firefox Mobile (Gecko)</th> + <th>Android</th> + <th>Edge</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>32</td> + <td>3</td> + <td>{{CompatVersionUnknown}}</td> + <td>10</td> + <td>11.5</td> + <td>6.1</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Prior to Gecko 2.0 beta 7 (Firefox 4.0 beta 7), all {{domxref("Blob")}} parameters below were {{domxref("File")}} parameters; this has since been updated to match the specification correctly. Prior to Gecko 13.0 {{geckoRelease("13.0")}} the <code>FileReader.error</code> property returned a {{domxref("FileError")}} object. This interface has been removed and <code>FileReader.error</code> is now returning the {{domxref("DOMError")}} object as defined in the latest FileAPI draft.</p> + +<p>[2] IE9 has a <a href="http://html5labs.interoperabilitybridges.com/prototypes/fileapi/fileapi/info">File API Lab</a>.</p> + +<p>[3] Opera has <a href="http://www.opera.com/docs/specs/presto28/file/">partial support</a> in 11.1.</p> + +<h2 id="閱讀更多">閱讀更多</h2> + +<ul> + <li>{{domxref("FileReader")}}</li> +</ul> diff --git a/files/zh-tw/web/api/filereader/index.html b/files/zh-tw/web/api/filereader/index.html new file mode 100644 index 0000000000..4b80e334a4 --- /dev/null +++ b/files/zh-tw/web/api/filereader/index.html @@ -0,0 +1,213 @@ +--- +title: FileReader +slug: Web/API/FileReader +tags: + - API + - File API + - Files + - Interface + - Reference +translation_of: Web/API/FileReader +--- +<div>{{APIRef("File API")}}</div> + +<p>藉由 <code>FileReader</code> 物件，Web 應用程式能以非同步（asynchronously）方式讀取儲存在用戶端的檔案（或原始資料暫存）內容，可以使用 {{domxref("File")}} 或 {{domxref("Blob")}} 物件指定要讀取的資料。</p> + +<p>File 物件可以從使用者於 {{HTMLElement("input")}} 元素選擇之檔案所回傳的 {{domxref("FileList")}} 物件當中取得，或是來自<a href="/docs/Web/Guide/HTML/Drag_and_drop">拖放操作</a>所產生的 {{domxref("DataTransfer")}} 物件之中，也能由 {{domxref("HTMLCanvasElement")}} 物件（元素物件）執行 <code>mozGetAsFile()</code> 方法後回傳。</p> + +<p>{{AvailableInWorkers}}</p> + +<h2 id="建構式">建構式</h2> + +<dl> + <dt>{{domxref("FileReader.FileReader", "FileReader()")}}</dt> + <dd>建立新的 <code>FileReader</code> 物件。</dd> +</dl> + +<p>請參考<a href="/docs/Using_files_from_web_applications">在網頁應用程式中使用本地檔案</a>的更多細節與範例。</p> + +<h2 id="屬性">屬性</h2> + +<dl> + <dt>{{domxref("FileReader.error")}} {{readonlyinline}}</dt> + <dd>此 {{domxref("DOMException")}} 類型的物件記錄了讀取資料時發生的錯誤資訊。</dd> + <dt>{{domxref("FileReader.readyState")}} {{readonlyinline}}</dt> + <dd>表示目前 <code>FileReader</code> 狀態的數字，其代表的意義為： + <table class="standard-table"> + <tbody> + <tr> + <td><code>EMPTY</code></td> + <td><code>0</code></td> + <td>尚未讀入任何資料。</td> + </tr> + <tr> + <td><code>LOADING</code></td> + <td><code>1</code></td> + <td>正在讀入資料。</td> + </tr> + <tr> + <td><code>DONE</code></td> + <td><code>2</code></td> + <td>完成資料讀取。</td> + </tr> + </tbody> + </table> + </dd> + <dt>{{domxref("FileReader.result")}} {{readonlyinline}}</dt> + <dd>讀入的資料內容。只有在讀取完成之後此屬性才有效，而資料的格式則取決於是由哪一個方法進行讀取。</dd> +</dl> + +<h3 id="事件處理器">事件處理器</h3> + +<dl> + <dt>{{domxref("FileReader.onabort")}}</dt> + <dd>{{event("abort")}} 事件處理器，於讀取被中斷時觸發。</dd> + <dt>{{domxref("FileReader.onerror")}}</dt> + <dd>{{event("error")}} 事件處理器，於讀取發生錯誤時觸發。</dd> + <dt>{{domxref("FileReader.onload")}}</dt> + <dd>{{event("load")}} 事件處理器，於讀取完成時觸發。</dd> + <dt>{{domxref("FileReader.onloadstart")}}</dt> + <dd>{{event("loadstart")}} 事件處理器，於讀取開始時觸發。</dd> + <dt>{{domxref("FileReader.onloadend")}}</dt> + <dd>{{event("loadend")}} 事件處理器，於每一次讀取結束之後觸發（不論成功或失敗），會於 <code>onload</code> 或 <code>onerror</code> 事件處理器之後才執行。</dd> + <dt>{{domxref("FileReader.onprogress")}}</dt> + <dd>{{event("progress")}} 事件處理器，於讀取 {{domxref("Blob")}} 內容時觸發。</dd> +</dl> + +<div class="note"> +<p><code>FileReader</code> 物件繼承自 {{domxref("EventTarget")}}，其所有的事件也都能夠透過 {{domxref("EventTarget.addEventListener()","addEventListener")}} 方法來註冊事件監聽器。</p> +</div> + +<h2 id="方法">方法</h2> + +<dl> + <dt>{{domxref("FileReader.abort()")}}</dt> + <dd>中斷目前的讀取，此方法回傳後屬性 <code>readyState</code> 將會是 <code>DONE</code>。</dd> + <dt>{{domxref("FileReader.readAsArrayBuffer()")}} {{gecko_minversion_inline("7.0")}}</dt> + <dd>開始讀取指定的 {{domxref("Blob")}}，讀取完成後屬性 <code>result</code> 將以 {{domxref("ArrayBuffer")}} 物件來表示讀入的資料內容。</dd> + <dt>{{domxref("FileReader.readAsBinaryString()")}} {{non-standard_inline}}</dt> + <dd>開始讀取指定的 {{domxref("Blob")}}，讀取完成後屬性 <code>result</code> 將以字串型式來表示讀入的原始二進位資料（raw binary data）。</dd> + <dt>{{domxref("FileReader.readAsDataURL()")}}</dt> + <dd>開始讀取指定的 {{domxref("Blob")}}，讀取完成後屬性 <code>result</code> 將以 <code>data:</code> URL 格式（base64 編碼）的字串來表示讀入的資料內容。</dd> + <dt>{{domxref("FileReader.readAsText()")}}</dt> + <dd>開始讀取指定的 {{domxref("Blob")}}，讀取完成後屬性 <code>result</code> 將以文字字串型式來表示讀入的資料內容。</dd> +</dl> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">註解</th> + </tr> + <tr> + <td>{{SpecName("File API", "#dfn-filereader", "FileReader")}}</td> + <td>{{Spec2("File API")}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>功能</th> + <th>Firefox (Gecko)</th> + <th>Chrome</th> + <th>Edge</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>基本支援</td> + <td>{{CompatGeckoDesktop("1.9.2")}}<sup>[1]</sup></td> + <td>7</td> + <td>{{CompatVersionUnknown}}</td> + <td>10<sup>[2]</sup></td> + <td>12.02<sup>[2]</sup></td> + <td>6.0</td> + </tr> + <tr> + <td>在 Web Workers 的支援</td> + <td>{{CompatGeckoDesktop(46)}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>error</code> property uses {{domxref("DOMException")}}, not {{domxref("DOMError")}}</td> + <td>{{CompatGeckoDesktop(58)}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{CompatVersionUnknown()}}</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>功能</th> + <th>Firefox Mobile (Gecko)</th> + <th>Android</th> + <th>Edge</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>基本支援</td> + <td>32</td> + <td>3</td> + <td>{{CompatVersionUnknown}}</td> + <td>10</td> + <td>11.5</td> + <td>6.1</td> + </tr> + <tr> + <td>在 Web Workers 的支援</td> + <td>{{CompatGeckoMobile(46)}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>error</code> property uses {{domxref("DOMException")}}, not {{domxref("DOMError")}}</td> + <td>{{CompatGeckoMobile(58)}}</td> + <td>{{CompatUnknown()}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] 在 Gecko 2.0 beta 7 (Firefox 4.0 beta 7) 以前，所有的 {{domxref("Blob")}} 參數都屬於 {{domxref("File")}} 參數；之後為了更符合規範，所以更新了這個特徵。在 Gecko 13.0 {{geckoRelease("13.0")}} 以前，<code>FileReader.error</code> 屬性回傳了 {{domxref("FileError")}} 物件。這個介面之後被移除、而 <code>FileReader.error</code> 目前會回傳 {{domxref("DOMError")}} 並定義為 FileAPI draft。</p> + +<p>[2] Opera 在 11.1 <a href="http://www.opera.com/docs/specs/presto28/file/">有限度支援</a>。</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/docs/Using_files_from_web_applications">在網頁應用程式中使用本地檔案</a></li> + <li>{{domxref("File")}}</li> + <li>{{domxref("Blob")}}</li> +</ul> diff --git a/files/zh-tw/web/api/filereader/readystate/index.html b/files/zh-tw/web/api/filereader/readystate/index.html new file mode 100644 index 0000000000..f6ff1fa5f6 --- /dev/null +++ b/files/zh-tw/web/api/filereader/readystate/index.html @@ -0,0 +1,98 @@ +--- +title: FileReader.readyState +slug: Web/API/FileReader/readyState +translation_of: Web/API/FileReader/readyState +--- +<div>{{APIRef("File API")}}</div> + +<p>提供目前讀取狀態</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">var state = <em>instanceOfFileReader</em>.readyState +</pre> + +<h2 id="數值">數值</h2> + +<p>數字代表 {{domxref("FileReader")}} API 三個可能的狀態：</p> + +<p>{{page("/en-US/docs/Web/API/FileReader","State constants")}}</p> + +<h2 id="規格">規格</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規格</th> + <th scope="col">狀態</th> + <th scope="col">說明</th> + </tr> + <tr> + <td>{{SpecName("File API", "#FileReader-interface", "FileReader")}}</td> + <td>{{Spec2("File API")}}</td> + <td>初始化定義</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>功能</th> + <th>Firefox (Gecko)</th> + <th>Chrome</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>基本支援</td> + <td>{{CompatGeckoDesktop("1.9.2")}}<sup>[1]</sup></td> + <td>7</td> + <td>10<sup>[2]</sup></td> + <td>12.02<sup>[3]</sup></td> + <td>6.0.2</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>功能</th> + <th>Firefox 手機版 (Gecko)</th> + <th>Android</th> + <th>IE 手機版</th> + <th>Opera 手機版</th> + <th>Safari 手機版</th> + </tr> + <tr> + <td>基本支援</td> + <td>32</td> + <td>3</td> + <td>10</td> + <td>11.5</td> + <td>6.1</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Prior to Gecko 2.0 beta 7 (Firefox 4.0 beta 7), all {{domxref("Blob")}} parameters below were {{domxref("File")}} parameters; this has since been updated to match the specification correctly. Prior to Gecko 13.0 {{geckoRelease("13.0")}} the <code>FileReader.error</code> property returned a {{domxref("FileError")}} object. This interface has been removed and <code>FileReader.error</code> is now returning the {{domxref("DOMError")}} object as defined in the latest FileAPI draft.</p> + +<p>[2] IE9 has a <a href="http://html5labs.interoperabilitybridges.com/prototypes/fileapi/fileapi/info">File API Lab</a>.</p> + +<p>[3] Opera has <a href="http://www.opera.com/docs/specs/presto28/file/">partial support</a> in 11.1.</p> + +<h2 id="閱讀更多">閱讀更多</h2> + +<ul> + <li>{{domxref("Blob")}}</li> +</ul> diff --git a/files/zh-tw/web/api/filesystem/index.html b/files/zh-tw/web/api/filesystem/index.html new file mode 100644 index 0000000000..49b4f70b84 --- /dev/null +++ b/files/zh-tw/web/api/filesystem/index.html @@ -0,0 +1,118 @@ +--- +title: FileSystem +slug: Web/API/FileSystem +tags: + - 檔案系統 +translation_of: Web/API/FileSystem +--- +<p>{{APIRef("File System API")}} {{non-standard_header}}</p> + +<p><strong><code>FileSystem </code></strong><code>實作文件和目錄介面，描述一個檔案系統。在任何檔案系統上，這個物件包含</code> {{domxref("FileSystemEntry.filesystem", "filesystem")}}的特性。某些網頁瀏覽器提供額外的API去創建和管理檔案系統，如Google Chrome的{{domxref("LocalFileSystem.requestFileSystem", "requestFileSystem()")}}函式。</p> + +<div class="note"> +<p>此介面並非標準API, 代表規格並未依造標準制定, 因此必須注意並非所有網頁瀏覽器都有實作此介面, 有實作的網頁瀏覽器可能只有實作一小部分. 請在{{anch("Browser compatibility")}} 查看更多細節.</p> +</div> + +<h2 id="基礎概念">基礎概念</h2> + +<p>存取 <code>FileSystem</code> 物件的兩種方法:</p> + +<ol> + <li>你可以直接要求一個使用<code>window.requestFileSystem()，</code>只用在你的網頁應用程式的沙盒類型 <code>FileSystem 物件。如果要求成功，將會執行</code>callback handler去接收描述檔案系統的<code>FileSystem物件參數。</code></li> + <li>你可以從檔案系統接口物件取得，透過他的{{domxref("FileSystemEntry.filesystem", "filesystem")}}特性</li> +</ol> + +<h2 id="屬性">屬性</h2> + +<dl> + <dt>{{domxref("FileSystem.name")}} {{ReadOnlyInline}}</dt> + <dd>{{domxref("USVString")}} 代表檔案系統的名稱. 此名稱在整個已宣告的檔案系統清單中是唯一的。</dd> + <dt>{{domxref("FileSystem.root")}} {{ReadOnlyInline}}</dt> + <dd> {{domxref("FileSystemDirectoryEntry")}} 物件表示檔案系統的根目錄。 透過此物件, 你可以取得權限存取所有檔案系統中的文件和目錄</dd> +</dl> + +<h2 id="規範">規範</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('File System API')}}</td> + <td>{{Spec2('File System API')}}</td> + <td>Draft of proposed API</td> + </tr> + </tbody> +</table> + +<p>This API has no official W3C or WHATWG specification.</p> + +<h2 id="Browser_compatibility" name="Browser_compatibility">瀏覽器相容性</h2> + +<p>{{ CompatibilityTable }}</p> + +<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>Microsoft Edge</th> + <th>Opera</th> + <th>Safari (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>13{{ property_prefix("webkit") }}</td> + <td>{{ CompatGeckoDesktop(50) }}</td> + <td>{{ CompatNo }}</td> + <td>{{CompatVersionUnknown}}<sup>[1]</sup></td> + <td>{{ CompatNo }}</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>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{ CompatNo }}</td> + <td>0.16{{ property_prefix("webkit") }}</td> + <td>{{ CompatGeckoMobile(50) }}</td> + <td>{{ CompatNo }}</td> + <td>{{ CompatNo }}</td> + <td>{{ CompatNo }}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Microsoft Edge 使用 <code>WebKitFileSystem 名稱實作</code>, 且只被用在 drag-and-drop scenarios 透過 {{domxref("DataTransferItem.webkitGetAsEntry()")}} 函式. 此函式不被使用在文件和目錄選擇的面板( 如當你以{{domxref("HTMLInputElement.webkitdirectory")}} 標籤使用 {{HTMLElement("input")}} 物件</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/File_and_Directory_Entries_API">File and Directory Entries API</a></li> + <li><a href="/en-US/docs/Web/API/File_and_Directory_Entries_API/Introduction">Introduction to the File System API</a></li> + <li>{{domxref("FileSystemEntry")}}, {{domxref("FileSystemFileEntry")}}, and {{domxref("FileSystemDirectoryEntry")}}</li> + <li>MSDN 文章: <a href="https://msdn.microsoft.com/library/mt732564">WebKitFileSystem object</a></li> +</ul> 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> diff --git a/files/zh-tw/web/api/fullscreen_api/index.html b/files/zh-tw/web/api/fullscreen_api/index.html new file mode 100644 index 0000000000..182f96c922 --- /dev/null +++ b/files/zh-tw/web/api/fullscreen_api/index.html @@ -0,0 +1,240 @@ +--- +title: 使用全螢幕模式 +slug: Web/API/Fullscreen_API +translation_of: Web/API/Fullscreen_API +--- +<p>{{DefaultAPISidebar("Fullscreen API")}}</p> + +<p class="summary">全螢幕 API 提供一個簡便的方式使網頁可以使用佔用使用者的整個螢幕的方式來顯示內容。該 API 讓您能夠容易地指示瀏覽器使某個元素及其子系（如有）佔用整個螢幕，並隱藏螢幕上所有瀏覽器使用者介面及其他應用程式。</p> + +<div class="note">目前並非所有瀏覽器均使用 API 的沒有前綴的版本。請查閱有關前綴以及名稱差異的表格（您也可以使用 Fscreen 來提供跨瀏覽器 API 存取）。</div> + +<h2 id="Specification" name="Specification">啟動全螢幕模式</h2> + +<p>如果您有一個元素打算以全螢幕模式展示（例如 {{ HTMLElement("video") }}），您可以呼叫該元素之 {{ domxref("Element.requestFullscreen()") }} 方法使之以全螢幕模式顯示。</p> + +<p>考慮此 {{ HTMLElement("video") }} 元素：</p> + +<pre class="brush: html"><video controls id="myvideo"> + <source src="somevideo.webm"></source> + <source src="somevideo.mp4"></source> +</video> +</pre> + +<p>我們可以使用指令碼將此影片全螢幕顯示：</p> + +<pre class="brush: js">var elem = document.getElementById("myvideo"); +if (elem.requestFullscreen) { + elem.requestFullscreen(); +} else if (elem.msRequestFullscreen) { + elem.msRequestFullscreen(); +} else if (elem.mozRequestFullScreen) { + elem.mozRequestFullScreen(); +} else if (elem.webkitRequestFullscreen) { + elem.webkitRequestFullscreen(); +} +</pre> + +<h3 id="呈現差異">呈現差異</h3> + +<p>值得留意的是，Gecko 及 WebKit 的實作有關鍵分別：Gecko 會增加 CSS 規則讓全螢幕的元素展延至填滿整個螢幕："<code>width: 100%; height: 100%</code>"。WebKit 則不會執行此動作，取而代之的是把該元素置中，並以原先的大小顯示。要取得同樣的全螢幕行為，您需要為該元素自行添加 "<code>width: 100%; height: 100%;</code>" 的 CSS 規則：</p> + +<pre class="brush: css">#myvideo:-webkit-full-screen { + width: 100%; + height: 100%; +} +</pre> + +<p>另一方面，如果您嘗試在 Gecko 上模擬 WebKit 的行為，您需要把呈現的元素放置在另一個實際調整為全螢幕的元素裡面，再使用 CSS 規則來調整內部元素至您想要的外觀。</p> + +<h3 id="通知">通知</h3> + +<p>如果成功進入全螢幕模式，包含該元素的文件將會接收到 {{ event("fullscreenchange") }} 事件。當離開全螢幕模式時，則會收到 {{ event("fullscreenchange") }} 事件。注意 {{ event("fullscreenchange") }} 事件並不提供任何資訊指示進入或離開全螢幕模式，但如果文件的 {{ domxref("document.fullscreenElement", "fullscreenElement") }} 屬性的值不為 null，則表示您正在處於全螢幕模式。</p> + +<h3 id="全螢幕要求失敗">全螢幕要求失敗</h3> + +<p>並不是所有情況下都保證可以進入全螢幕模式。例如，{{ HTMLElement("iframe") }} 元素含有 {{ HTMLAttrXRef("allowfullscreen", "iframe") }} 屬性來選擇是否容許其內容能以全螢幕方式呈現。而且，例如視窗式外掛程式等的某些內容並不可以在全螢幕模式中顯示。把無法呈現為全螢幕的元素設定為全螢幕模式的嘗試都沒有作用，而要求顯示為全螢幕的元素會接收到 <code>mozfullscreenerror</code> 事件。當全螢幕要求失敗時，Firefox 會在網頁主控台上紀錄一則錯誤訊息，解釋要求失敗的原因。但在 Chrome 以及新版的 Opera 上，則不會產生這些錯誤訊息。</p> + +<div class="note"> +<p><strong>注意：</strong>全螢幕要求必須在事件處理常式中呼叫，否則將會被拒絕。</p> +</div> + +<h2 id="離開全螢幕模式">離開全螢幕模式</h2> + +<p>使用者永遠可以自行離開全螢幕模式，詳見 {{ anch("Things your users want to know") }}。您也可以呼叫 {{domxref("Document.exitFullscreen()")}} 方法來達到相同效果。</p> + +<h2 id="其他資訊">其他資訊</h2> + +<p>{{ domxref("document") }} 提供一些附加資訊，對於開發全螢幕網頁應用程式的時候非常有用：</p> + +<dl> + <dt>{{ domxref("document.fullscreenElement", "fullscreenElement") }}</dt> + <dd><code>fullscreenElement</code> 屬性傳回正在顯示為全螢幕模式的 {{ domxref("element") }}。如其為非 null 值，表示文件目前在全螢幕模式。如其為 null，表示文件目前不在全螢幕模式。</dd> + <dt>{{ domxref("document.fullscreenEnabled", "fullscreenEnabled") }}</dt> + <dd><code>fullscreenEnabled</code> 屬性傳回文件是否容許您要求進入全螢幕訊息。</dd> +</dl> + +<h2 id="Things_your_users_want_to_know" name="Things_your_users_want_to_know">使用者可能想了解的訊息</h2> + +<p>您可能會讓使用者知道他們可以按 <kbd>ESC</kbd> 或 <kbd>F11</kbd> 鍵來離開全螢幕模式。</p> + +<p>此外，瀏覽其他頁面、切換分頁、或切換到其他應用程式（例如按 鍵）亦會離開全螢幕模式。</p> + +<h2 id="Specification" name="Specification">範例</h2> + +<p>In this example, a video is presented in a web page. Pressing the Return or Enter key lets the user toggle between windowed and fullscreen presentation of the video.</p> + +<p><a href="/samples/domref/fullscreen.html">查看示例</a></p> + +<h3 id="監視_Enter_鍵">監視 Enter 鍵</h3> + +<p>When the page is loaded, this code is run to set up an event listener to watch for the 'enter' key.</p> + +<pre class="brush: js">document.addEventListener("keydown", function(e) { + if (e.keyCode == 13) { + toggleFullScreen(); + } +}, false); +</pre> + +<h3 id="Toggling_fullscreen_mode">Toggling fullscreen mode</h3> + +<p>This code is called when the user hits the Enter key, as seen above.</p> + +<pre class="brush: js">function toggleFullScreen() { + if (!document.fullscreenElement && // alternative standard method + !document.mozFullScreenElement && !document.webkitFullscreenElement && !document.msFullscreenElement ) { // current working methods + if (document.documentElement.requestFullscreen) { + document.documentElement.requestFullscreen(); + } else if (document.documentElement.msRequestFullscreen) { + document.documentElement.msRequestFullscreen(); + } else if (document.documentElement.mozRequestFullScreen) { + document.documentElement.mozRequestFullScreen(); + } else if (document.documentElement.webkitRequestFullscreen) { + document.documentElement.webkitRequestFullscreen(Element.ALLOW_KEYBOARD_INPUT); + } + } else { + if (document.exitFullscreen) { + document.exitFullscreen(); + } else if (document.msExitFullscreen) { + document.msExitFullscreen(); + } else if (document.mozCancelFullScreen) { + document.mozCancelFullScreen(); + } else if (document.webkitExitFullscreen) { + document.webkitExitFullscreen(); + } + } +} +</pre> + +<p>This starts by looking at the value of the <code>fullscreenElement</code> attribute on the {{ domxref("document") }} (checking it prefixed with both <code>moz</code>,<code> ms</code>,<code> </code>and <code>webkit</code>). If it's <code>null</code>, the document is currently in windowed mode, so we need to switch to fullscreen mode. Switching to fullscreen mode is done by calling either {{ domxref("element.mozRequestFullScreen()") }} <code>msRequestFullscreen()</code>or <code>webkitRequestFullscreen()</code>, depending on which is available.</p> + +<p>If fullscreen mode is already active (<code>fullscreenElement</code> is non-<code>null</code>), we call {{ domxref("document.mozCancelFullScreen()") }}, <code>msExitFullscreen</code> or <code>webkitExitFullscreen()</code>, again depending on which browser is in use.</p> + +<h2 id="Browser_compatibility" name="Browser_compatibility">瀏覽器兼容性</h2> + +<p>Although Gecko , Trident, and WebKit implement a draft of this API, there are some subtle differences. This document doesn't necessarily try to call them all into focus. The article will be revised as the spec and implementations fall closer into alignment with one another.</p> + +<p>{{ CompatibilityTable() }}</p> + +<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>15 {{ property_prefix("-webkit") }}</td> + <td>{{ CompatGeckoDesktop("9.0") }} {{ property_prefix("-moz") }}</td> + <td>11 {{ property_prefix("-ms") }}</td> + <td>12.10</td> + <td>5.0 {{ property_prefix("-webkit") }}</td> + </tr> + <tr> + <td><code>fullscreenEnabled</code></td> + <td>20 {{ property_prefix("-webkit") }}</td> + <td>{{ CompatGeckoDesktop("10.0") }} {{ property_prefix("-moz") }}</td> + <td>11 {{ property_prefix("-ms") }}</td> + <td>12.10</td> + <td>5.1 {{ property_prefix("-webkit") }}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{ CompatUnknown() }}</td> + <td>28 {{ property_prefix("-webkit") }}</td> + <td>{{ CompatGeckoMobile("9.0") }}{{ property_prefix("-moz") }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + <tr> + <td><code>fullscreenEnabled</code></td> + <td>{{ CompatUnknown() }}</td> + <td>28 {{ property_prefix("-webkit") }}</td> + <td>{{ CompatGeckoMobile("10.0") }} {{ property_prefix("moz") }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + </tbody> +</table> +</div> + +<h3 id="Gecko_notes">Gecko notes</h3> + +<p>Although this API was introduced in Gecko 9.0 {{ geckoRelease("9.0") }}, it's not enabled by default in that release. To enable it, set the <code>full-screen-api.enabled</code> preference to <code>true</code>. The API is enabled by default in Gecko 10.0 {{ geckoRelease("10.0") }}. In Gecko all the API is spelt "fullScreen".</p> + +<h2 id="Specification" name="Specification">規範</h2> + +<p><a class="external" href="http://fullscreen.spec.whatwg.org/">Fullscreen API</a></p> + +<h2 id="非標準方法">非標準方法</h2> + +<p>These are some of the methods that browsers implemented before the standard was drafted. Having the standard methods described above it's better to avoid using the following ones:</p> + +<ul> + <li><a href="/en-US/docs/DOM/window.fullScreen" title="/en-US/docs/DOM/window.fullScreen"><code>window.fullScreen</code></a> (Firefox)</li> + <li><code>HTMLMediaElement.webkitDisplayingFullscreen</code></li> + <li><code>HTMLMediaElement.webkitEnterFullscreen</code></li> + <li><code>HTMLMediaElement.webkitExitFullscreen</code></li> + <li><code>HTMLMediaElement.webkitSupportsFullscreen</code></li> +</ul> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{ domxref("element.mozRequestFullScreen()") }}</li> + <li>{{ domxref("element.mozCancelFullScreen()") }}</li> + <li>{{ domxref("document.mozFullScreen") }}</li> + <li>{{ domxref("document.mozFullScreenElement") }}</li> + <li>{{ domxref("document.mozFullScreenEnabled") }}</li> + <li>{{ cssxref(":-moz-full-screen") }}</li> + <li>{{ cssxref(":-moz-full-screen-ancestor") }}</li> + <li>{{ HTMLAttrXRef("allowfullscreen", "iframe") }}</li> +</ul> + +<ul> + <li><a class="external" href="http://blog.pearce.org.nz/2011/11/firefoxs-html-full-screen-api-enabled.html" title="http://blog.pearce.org.nz/2011/11/firefoxs-html-full-screen-api-enabled.html">Blog post: Firefox's HTML full-screen API enabled in Nightly builds</a></li> +</ul> diff --git a/files/zh-tw/web/api/gainnode/gain/index.html b/files/zh-tw/web/api/gainnode/gain/index.html new file mode 100644 index 0000000000..895a356e25 --- /dev/null +++ b/files/zh-tw/web/api/gainnode/gain/index.html @@ -0,0 +1,113 @@ +--- +title: GainNode.gain +slug: Web/API/GainNode/gain +tags: + - API +translation_of: Web/API/GainNode/gain +--- +<p>{{ APIRef("Web Audio API") }}</p> + +<div> +<p>{{ domxref("GainNode") }} 介面的 <code>gain</code> 屬性是 <a href="/en-US/docs/Web/API/AudioParam#a-rate">a-rate</a> {{domxref("AudioParam")}}，代表增益的數值。</p> +</div> + +<h2 id="語法">語法</h2> + +<pre class="brush: js">var audioCtx = new AudioContext(); +var gainNode = audioCtx.createGain(); +gainNode.gain.value = 0.5; +</pre> + +<h3 id="傳回值">傳回值</h3> + +<p>一個 {{domxref("AudioParam")}}.</p> + +<div class="note"> +<p><strong>註：</strong> 雖然傳回的 <code>AudioParam</code> 是唯讀的，但是它所代表的值可以更改。</p> +</div> + +<h2 id="範例">範例</h2> + +<p>{{page("/en-US/docs/Web/API/AudioContext.createGain","Example")}}</p> + +<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('Web Audio API', '#widl-GainNode-gain', 'gain')}}</td> + <td>{{Spec2('Web Audio API')}}</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>Edge</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatChrome(10.0)}}{{property_prefix("webkit")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(25.0)}} </td> + <td>{{CompatNo}}</td> + <td>15.0{{property_prefix("webkit")}}<br> + 22 (unprefixed)</td> + <td>6.0{{property_prefix("webkit")}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS</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>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>26.0</td> + <td>1.2</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>33.0</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/en-US/docs/Web_Audio_API/Using_Web_Audio_API">Using the Web Audio API</a></li> +</ul> diff --git a/files/zh-tw/web/api/gainnode/index.html b/files/zh-tw/web/api/gainnode/index.html new file mode 100644 index 0000000000..1d52092799 --- /dev/null +++ b/files/zh-tw/web/api/gainnode/index.html @@ -0,0 +1,168 @@ +--- +title: GainNode +slug: Web/API/GainNode +translation_of: Web/API/GainNode +--- +<p>{{ APIRef("Web Audio API") }}</p> + +<div> +<p><code>GainNode</code> 介面代表的是音量改變。 這是 {{domxref("AudioNode")}} 音訊處理模組，可以對輸入的訊號做增益 (gain) 後輸出。一個 <code>GainNode</code> 有一個輸入和一個輸出，兩者有相同的聲道數。</p> +</div> + +<p>增益 (gain) 是無單位的數值，隨時間變化，會用來和所有輸入聲道的取樣做相乘。 如果更改的話，新的增益會用 de-zippering 演算法處理，以避免輸出聲音出現難聽的「喀」聲。</p> + +<p><img alt="The GainNode is increasing the gain of the output." src="https://mdn.mozillademos.org/files/5085/WebAudioGainNode.png" style="height: 116px; width: 774px;"></p> + +<table class="properties"> + <tbody> + <tr> + <th scope="row">Number of inputs</th> + <td><code>1</code></td> + </tr> + <tr> + <th scope="row">Number of outputs</th> + <td><code>1</code></td> + </tr> + <tr> + <th scope="row">Channel count mode</th> + <td><code>"max"</code></td> + </tr> + <tr> + <th scope="row">Channel count</th> + <td><code>2</code> (not used in the default count mode)</td> + </tr> + <tr> + <th scope="row">Channel interpretation</th> + <td><code>"speakers"</code></td> + </tr> + </tbody> +</table> + +<h2 id="Constructor">Constructor</h2> + +<dl> + <dt>{{domxref("GainNode.GainNode", "GainNode()")}}</dt> + <dd>Creates a new instance of an GainNode object.</dd> +</dl> + +<h2 id="Properties">Properties</h2> + +<p><em>Inherits properties from its parent, </em><em>{{domxref("AudioNode")}}</em>.</p> + +<dl> + <dt>{{domxref("GainNode.gain")}} {{readonlyinline}}</dt> + <dd>是 <a href="/en-US/docs/Web/API/AudioParam#a-rate">a-rate</a> {{domxref("AudioParam")}} ，代表增益值</dd> +</dl> + +<h2 id="Methods">Methods</h2> + +<p><em>No specific method; inherits methods from its parent, </em><em>{{domxref("AudioNode")}}</em>.</p> + +<h2 id="Example">Example</h2> + +<p>{{page("/en-US/docs/Web/API/AudioContext.createGain","Example")}}</p> + +<h2 id="Specifications">Specifications</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('Web Audio API', '#the-gainnode-interface', 'GainNode')}}</td> + <td>{{Spec2('Web Audio API')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatChrome(10.0)}}{{property_prefix("webkit")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(25.0)}} </td> + <td>{{CompatNo}}</td> + <td>{{CompatOpera(15)}}{{property_prefix("webkit")}}<br> + {{CompatOpera(22)}}</td> + <td>6.0{{property_prefix("webkit")}}</td> + </tr> + <tr> + <td>constructor</td> + <td>{{CompatChrome(55.0)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatOpera(42)}}</td> + <td>{{CompatUnknown}}</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</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>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>26.0</td> + <td>1.2</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatChrome(33.0)}}</td> + </tr> + <tr> + <td>constructor</td> + <td>{{CompatNo}}</td> + <td>{{CompatChrome(55.0)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatOpera(42)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatChrome(55.0)}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/Web_Audio_API/Using_Web_Audio_API">Using the Web Audio API</a></li> +</ul> diff --git a/files/zh-tw/web/api/geolocation/clearwatch/index.html b/files/zh-tw/web/api/geolocation/clearwatch/index.html new file mode 100644 index 0000000000..c1d2979db2 --- /dev/null +++ b/files/zh-tw/web/api/geolocation/clearwatch/index.html @@ -0,0 +1,132 @@ +--- +title: Geolocation.clearWatch() +slug: Web/API/Geolocation/clearWatch +translation_of: Web/API/Geolocation/clearWatch +--- +<p>{{ APIref("Geolocation API") }}</p> + +<p><strong><code>Geolocation.clearWatch()</code></strong> 這個函式是用來取消 {{domxref("Geolocation.watchPosition()")}} 註冊的函式。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">navigator.geolocation.clearWatch(<em>id</em>);</pre> + +<h3 id="參數">參數</h3> + +<dl> + <dt><em>編號(id)</em></dt> + <dd>這個編號(ID) 是由 {{domxref("Geolocation.watchPosition()")}} 這個函式所回傳，當你不再需要收到位置更新時，你可以用此編號，取消 {{domxref("Geolocation.watchPosition()")}} 的註冊。</dd> +</dl> + +<h2 id="範例">範例</h2> + +<pre class="brush: js">var id, target, option; + +function success(pos) { + var crd = pos.coords; + + if (target.latitude === crd.latitude && target.longitude === crd.longitude) { + console.log('Congratulation, you reach the target'); + navigator.geolocation.clearWatch(id); + } +}; + +function error(err) { + console.warn('ERROR(' + err.code + '): ' + err.message); +}; + +target = { + latitude : 0, + longitude: 0, +} + +options = { + enableHighAccuracy: false, + timeout: 5000, + maximumAge: 0 +}; + +id = navigator.geolocation.watchPosition(success, error, options); +</pre> + +<h2 id="規格">規格</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('Geolocation')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + Removed in 15.0<br> + Reintroduced in 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown()}}</td> + <td>{{CompatUnknown()}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown()}}</td> + <td>10.60</td> + <td>{{CompatUnknown()}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation" title="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>{{domxref("Geolocation")}}</li> + <li>{{domxref("Geolocation.watchPosition()")}}</li> + <li>{{domxref("Geolocation.getCurrentPosition()")}}</li> +</ul> diff --git a/files/zh-tw/web/api/geolocation/getcurrentposition/index.html b/files/zh-tw/web/api/geolocation/getcurrentposition/index.html new file mode 100644 index 0000000000..78c26d3e8e --- /dev/null +++ b/files/zh-tw/web/api/geolocation/getcurrentposition/index.html @@ -0,0 +1,127 @@ +--- +title: Geolocation.getCurrentPosition() +slug: Web/API/Geolocation/getCurrentPosition +translation_of: Web/API/Geolocation/getCurrentPosition +--- +<p>{{ APIRef("Geolocation API") }}</p> + +<p><strong><code>Geolocation.getCurrentPosition()</code></strong> 方法用來獲取設備當前的位置。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">navigator.geolocation.getCurrentPosition(<em>success[</em>, <em>error[</em>, <em>options]]</em>)</pre> + +<h3 id="參數">參數</h3> + +<dl> + <dt><em>success</em></dt> + <dd>一個回呼函式(callback function) 會被傳入一個{{domxref("Position")}} 的物件。</dd> + <dt><em>error</em> {{optional_inline}}</dt> + <dd>一個選擇性的錯誤回呼函式(callback function)，會被傳入一個 {{domxref("PositionError")}} 的物件。</dd> + <dt><em>options</em> {{optional_inline}}</dt> + <dd>一個選擇性的 {{domxref("PositionOptions")}} 的物件。</dd> +</dl> + +<h2 id="範例">範例</h2> + +<pre class="brush: js">var options = { + enableHighAccuracy: true, + timeout: 5000, + maximumAge: 0 +}; + +function success(pos) { + var crd = pos.coords; + + console.log('Your current position is:'); + console.log('Latitude : ' + crd.latitude); + console.log('Longitude: ' + crd.longitude); + console.log('More or less ' + crd.accuracy + ' meters.'); +}; + +function error(err) { + console.warn('ERROR(' + err.code + '): ' + err.message); +}; + +navigator.geolocation.getCurrentPosition(success, error, options); +</pre> + +<h2 id="規格">規格</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('Geolocation')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + Removed in 15.0<br> + Reintroduced in 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown()}}</td> + <td>{{CompatUnknown()}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown()}}</td> + <td>10.60</td> + <td>{{CompatUnknown()}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation" title="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>{{domxref("Navigator.geolocation")}}</li> +</ul> diff --git a/files/zh-tw/web/api/geolocation/index.html b/files/zh-tw/web/api/geolocation/index.html new file mode 100644 index 0000000000..3dda732dbf --- /dev/null +++ b/files/zh-tw/web/api/geolocation/index.html @@ -0,0 +1,118 @@ +--- +title: Geolocation +slug: Web/API/Geolocation +tags: + - API + - Advanced + - Geolocation API + - Interface + - NeedsTranslation + - Reference + - TopicStub +translation_of: Web/API/Geolocation +--- +<div>{{APIRef("Geolocation API")}}</div> + +<p><code><strong>Geolocation</strong></code> 介面代表一個物件可以透過你的網頁程式去獲得你的裝置位置。這個介面提供了網站或應用程式根據使用者的位置去客製化呈現的內容。</p> + +<p>{{domxref("Navigator")}} 此物件實作了 {{domxref("Navigator.geolocation")}} 介面。</p> + +<div class="note"> +<p><strong>備註:</strong> 因為隱私的因素，當網頁要求存取位置資訊時，用戶會被提示通知並且詢問授權與否。注意不同的瀏覽器在詢問授權時有各自不同的策略和方式。</p> +</div> + +<h2 id="性質">性質</h2> + +<p><em><code>Geolocation</code> 介面沒有繼承也沒有時做任何方法</em>。</p> + +<h2 id="方法">方法</h2> + +<p><em><em><code>Geolocation</code> 介面沒有繼承任何方法</em></em>。</p> + +<dl> + <dt>{{domxref("Geolocation.getCurrentPosition()")}}</dt> + <dd>取得裝置當前位置，並回傳{{domxref("Position")}}。</dd> + <dt>{{domxref("Geolocation.watchPosition()")}}</dt> + <dd>返回一個長整數，註冊一個回呼函數。這個方法是用來註冊一個處理的函式，當使用者的裝置位置更新時，這個函式所傳入的回呼函式(callback function) 就會自動被呼叫。</dd> + <dt>{{domxref("Geolocation.clearWatch()")}}</dt> + <dd>移除指定註冊的<code> watchPosition()</code>。</dd> +</dl> + +<h2 id="規格">規格</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('Geolocation')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + Removed in 15.0<br> + Reintroduced in 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown()}}</td> + <td>{{CompatUnknown()}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown()}}</td> + <td>10.60</td> + <td>{{CompatUnknown()}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation" title="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> +</ul> diff --git a/files/zh-tw/web/api/geolocation/using_geolocation/index.html b/files/zh-tw/web/api/geolocation/using_geolocation/index.html new file mode 100644 index 0000000000..cdc56770c4 --- /dev/null +++ b/files/zh-tw/web/api/geolocation/using_geolocation/index.html @@ -0,0 +1,251 @@ +--- +title: 地理位置定位 (Geolocation) +slug: Web/API/Geolocation/Using_geolocation +translation_of: Web/API/Geolocation_API +--- +<p>Web Apps 若需要使用者的位置，可透過<strong> Geolocation API</strong> 取得相關資訊。而基於隱私權的考量，這些 Web Apps 均必須取得使用者的許可之後，才能發佈位置資訊。</p> + +<h2 id="地理位置定位_Geolocation_物件">地理位置定位 (Geolocation) 物件</h2> + +<p>Geolocation API，是透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.geolocation" title="The documentation about this has not yet been written; please consider contributing!"><code>navigator.geolocation</code></a> <code>物件</code>所發佈。</p> + +<p>若該物件可用，即可進行地理位置定位服務。因此可先測試地理位置定位是否存在：</p> + +<pre class="brush: js">if ("geolocation" in navigator) { + /* geolocation is available */ +} else { + /* geolocation IS NOT available */ +} +</pre> + +<div class="note"><strong>注意：</strong>在 Firefox 24 之後的版本，即使停用此 API，<code>navigator </code>中的「<code>geolocation」也同樣回傳</code> <code>true。此問題已根據規格而於</code> <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Releases/25/Site_Compatibility">Firefox 25</a> 中修正 (<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=884921" title="FIXED: Align navigator.geolocation with spec">bug 884921</a>)。</div> + +<h3 id="取得目前位置">取得目前位置</h3> + +<p>若要取得使用者目前的位置，可呼叫 <code>getCurrentPosition()</code> 函式。如此將啟動非同步化的請求，以偵測使用者的位置，並將查詢定位硬體而取得最新資訊。一旦決定位置，隨即執行特定的回呼常式 (Callback routine)。若發生錯誤，則可選擇是否提供第二次回呼。第三項參數為選項介面 (亦可選擇是否使用之)，可設定位置回傳的的最長時間，與請求的等待時間。<br> + 若不論定位精確度而想儘快固定單一位置，則可使用 <code>getCurrentPosition()</code>。以具備 GPS 的裝置為例，往往需耗時 1 分鐘或更長的時間而固定 GPS 資訊。也因此，<code>getCurrentPosition()</code> 可能取得較低精確度的資料 (IP 位置或 WiFi) 而隨即開始作業。</p> + +<div class="note"> +<p><strong>注意：</strong>依預設值，<a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.geolocation.getCurrentPosition" title="The Geolocation.getCurrentPosition() method is used to get the current position of the device."><code>getCurrentPosition()</code></a> 將儘快回傳較低精確度的結果。若不論精確度而只要儘快獲得答案，則可使用 <a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.geolocation.getCurrentPosition" title="The Geolocation.getCurrentPosition() method is used to get the current position of the device."><code>getCurrentPosition()</code></a>。舉例來說，搭載 GPS 的裝置可能需要一段時間才能取得 GPS 定位資訊，所以可能將低精確度的資料 (IP 位置或 Wifi) 回傳至 <a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.geolocation.getCurrentPosition" title="The Geolocation.getCurrentPosition() method is used to get the current position of the device."><code>getCurrentPosition()</code></a>。</p> +</div> + +<pre class="brush: js">navigator.geolocation.getCurrentPosition(function(position) { + do_something(position.coords.latitude, position.coords.longitude); +});</pre> + +<p>一旦取得定位位置之後，上列範例隨即將執行 <code>do_something() </code>函式。</p> + +<h3 id="觀看目前位置">觀看目前位置</h3> + +<p>如果定位資料改變 (可能是裝置移動，或取得更精確的地理位置資訊)，則可設定 1 組回呼函式，使其隨著更新過的定位資訊而呼叫之。而這個動作可透過 <code>watchPosition() 函式</code>完成。<a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.geolocation.watchPosition" title="The Geolocation.watchPosition() method is used to register a handler function that will be called automatically each time the position of the device changes. You can also, optionally, specify an error handling callback function."><code>watchPosition()</code></a> 所具備的輸入參數與 <code>getCurrentPosition() </code>相同。回呼函式將呼叫數次，讓瀏覽器可於使用者移動期間更新位置，或可根據目前所使用的不同定位技術，提供更精確的定位資訊。若一直未回傳有效結果，則錯誤回呼 (Error Callback) 函式僅將呼叫 1 次。另請注意，錯誤回呼函式僅限於 <code>getCurrentPosition()，因此為選填</code>。</p> + +<div class="note"> +<p><strong>注意：</strong>不需啟動 <a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.geolocation.getCurrentPosition" title="The Geolocation.getCurrentPosition() method is used to get the current position of the device."><code>getCurrentPosition()</code></a> 呼叫，亦可使用 <a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.geolocation.watchPosition" title="The Geolocation.watchPosition() method is used to register a handler function that will be called automatically each time the position of the device changes. You can also, optionally, specify an error handling callback function."><code>watchPosition()</code></a>。</p> +</div> + +<pre class="brush: js">var watchID = navigator.geolocation.watchPosition(function(position) { + do_something(position.coords.latitude, position.coords.longitude); +} +);</pre> + +<p><code>watchPosition()</code> 函式將回傳 1 組 ID 編號，專用以識別必要的定位監看員 (Watcher)。而此數值若搭配 <code>clearWatch() </code>函式，即可停止觀看使用者的位置。</p> + +<pre>navigator.geolocation.clearWatch(watchID); +</pre> + +<h3 id="微調回應">微調回應</h3> + +<p><a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.geolocation.getCurrentPosition" title="The Geolocation.getCurrentPosition() method is used to get the current position of the device."><code>getCurrentPosition()</code></a> 與 <a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.geolocation.watchPosition" title="The Geolocation.watchPosition() method is used to register a handler function that will be called automatically each time the position of the device changes. You can also, optionally, specify an error handling callback function."><code>watchPosition()</code></a> 均可容納 1 組成功回呼、1 組錯誤回呼 (選填)、1 組 <code>PositionOptions</code> 物件 (選填)。</p> + +<p>對 <a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.geolocation.watchPosition" title="The Geolocation.watchPosition() method is used to register a handler function that will be called automatically each time the position of the device changes. You can also, optionally, specify an error handling callback function."><code>watchPosition</code></a> 的呼叫應類似如下：</p> + +<pre class="brush: js">function geo_success(position) { + do_something(position.coords.latitude, position.coords.longitude); +} + +function geo_error() { + alert("Sorry, no position available."); +} + +var geo_options = { + enableHighAccuracy: true, + maximumAge : 30000, + timeout : 27000 +}; + +var wpid = navigator.geolocation.watchPosition(geo_success, geo_error, geo_options);</pre> + +<p><a id="fck_paste_padding">現成的 watchPosition Demo：</a><a class="external" href="http://www.thedotproduct.org/experiments/geo/">http://www.thedotproduct.org/experiments/geo/</a><br> + <a id="fck_paste_padding"></a></p> + +<h2 id="敘述位置">敘述位置</h2> + +<p>以 <code>Position</code> 物件參照 <code>Coordinates</code> 物件，即可敘述使用者的位置。</p> + +<h2 id="處理錯誤">處理錯誤</h2> + +<p>在呼叫 <code>getCurrentPosition()</code> 或 <code>watchPosition() 時，</code>若獲得錯誤回呼函式，則<code>錯誤回呼函式的第一組參數將為 PositionError 物件：</code></p> + +<pre>function errorCallback(<code>error</code>) { alert('ERROR(' +<code> error</code>.<code>code </code>+ '): ' +<code> error</code>.<code>message</code>);}; +</pre> + +<h2 id="地理位置定位實際範例">地理位置定位實際範例</h2> + +<h3 id="HTML_內容">HTML 內容</h3> + +<pre><p><button onclick="geoFindMe()"><code>Show my location</code></button></p> +<div id="out"></div></pre> + +<h3 id="JavaScript_內容">JavaScript 內容</h3> + +<pre class="brush: js;">function geoFindMe() { + var output = document.getElementById("out"); + + if (!navigator.geolocation){ + output.innerHTML = "<p>Geolocation is not supported by your browser</p>"; + return; + } + + function success(position) { + var latitude = position.coords.latitude; + var longitude = position.coords.longitude; + + output.innerHTML = '<p>Latitude is ' + latitude + '° <br>Longitude is ' + longitude + '°</p>'; + + var img = new Image(); + img.src = "http://maps.googleapis.com/maps/api/staticmap?center=" + latitude + "," + longitude + "&zoom=13&size=300x300&sensor=false"; + + output.appendChild(img); + }; + + function error() { + output.innerHTML = "Unable to retrieve your location"; + }; + + output.innerHTML = "<p>Locating…</p>"; + + navigator.geolocation.getCurrentPosition(success, error); +} +</pre> + +<h3 id="現場測試結果">現場測試結果</h3> + +<p>若無法顯示，可至本文右上角「Language」切換回英文原文觀看。</p> + + +<p>{{EmbedLiveSample('Examples', 350, 150, "", "", "", "geolocation")}}</p> + + +<h2 id="請求權限">請求權限</h2> + +<p>addons.mozilla.org 上所提供的任何附加元件，只要使用地理位置定位資料，均必須明確取得許可才能繼續作業。下列函式詢問許可的方法，則類似網頁詢問許可的自動提示方法，但更為簡單。若為可套用的狀態，則使用者的回應將儲存於 <code>pref</code> 參數所指定的偏好中。於 <code>callback</code> 參數中所提供的函式，將透過 1 組代表使用者反應的布林值而呼叫之。若使用者的回應為 <code>true</code>，則附加元件才會存取地理位置定位資料。</p> + +<pre class="brush: js">function prompt(window, pref, message, callback) { + let branch = Components.classes["@mozilla.org/preferences-service;1"] + .getService(Components.interfaces.nsIPrefBranch); + + if (branch.getPrefType(pref) === branch.PREF_STRING) { + switch (branch.getCharPref(pref)) { + case "always": + return callback(true); + case "never": + return callback(false); + } + } + + let done = false; + + function remember(value, result) { + return function() { + done = true; + branch.setCharPref(pref, value); + callback(result); + } + } + + let self = window.PopupNotifications.show( + window.gBrowser.selectedBrowser, + "geolocation", + message, + "geo-notification-icon", + { + label: "Share Location", + accessKey: "S", + callback: function(notification) { + done = true; + callback(true); + } + }, [ + { + label: "Always Share", + accessKey: "A", + callback: remember("always", true) + }, + { + label: "Never Share", + accessKey: "N", + callback: remember("never", false) + } + ], { + eventCallback: function(event) { + if (event === "dismissed") { + if (!done) callback(false); + done = true; + window.PopupNotifications.remove(self); + } + }, + persistWhileVisible: true + }); +} + +prompt(window, + "extensions.foo-addon.allowGeolocation", + "Foo Add-on wants to know your location.", + function callback(allowed) { alert(allowed); }); +</pre> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th>瀏覽器</th> + <th>基本支援</th> + <th><a class="external" href="http://dev.w3.org/geo/api/spec-source-v2.html">Geolocation Level 2</a></th> + </tr> + <tr> + <td>Internet Explorer</td> + <td>IE9 RC</td> + <td>---</td> + </tr> + <tr> + <td>Firefox (Gecko)</td> + <td><strong>3.5</strong> (1.9.1)</td> + <td>---</td> + </tr> + <tr> + <td>Opera</td> + <td><strong>10.60</strong></td> + <td>---</td> + </tr> + <tr> + <td>Safari | Chrome | WebKit</td> + <td>5 | 5 | 533</td> + <td>---</td> + </tr> + </tbody> +</table> + +<h2 id="Gecko_註記">Gecko 註記</h2> + +<p>Firefox 可透過 Google 的定位服務 (Google Location Services，GLS)，根據使用者的 WiFi 資訊而找出使用者的位置。與 Google 之間所交換的資料，包含 WiFi 存取點 (Access Point) 資料、Access token (類似 2 個禮拜的 cookie)、使用者的 IP 位址。若需更多資訊，可參閱 <a href="http://www.mozilla.com/en-US/legal/privacy/" title="http://www.mozilla.com/en-US/legal/privacy/">Mozilla 的隱私權政策</a>與 <a href="http://www.google.com/privacy-lsf.html" title="http://www.google.com/privacy-lsf.html">Google 的隱私權政策</a>。其內將詳述資料的使用方式。</p> + +<p>Firefox 3.6 (Gecko 1.9.2) 新支援了 <a href="http://catb.org/gpsd/" title="http://catb.org/gpsd/">GPSD</a> (GPS daemon) 服務，適合 Linux 的地理位置定位。</p> + +<h2 id="另請參閱">另請參閱</h2> + +<ul> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.geolocation" title="The documentation about this has not yet been written; please consider contributing!"><code>navigator.geolocation</code></a></li> + <li><a href="http://www.w3.org/TR/geolocation-API/" title="http://www.w3.org/TR/geolocation-API/">w3.org 的 Geolocation API </a></li> + <li><a href="https://developer.mozilla.org/en-US/demos/tag/tech:geolocation" title="en-US/demos/tag/tech:geolocation/">Geolocation API 相關 Demos</a></li> +</ul> diff --git a/files/zh-tw/web/api/geolocation/watchposition/index.html b/files/zh-tw/web/api/geolocation/watchposition/index.html new file mode 100644 index 0000000000..fc5109f1f5 --- /dev/null +++ b/files/zh-tw/web/api/geolocation/watchposition/index.html @@ -0,0 +1,143 @@ +--- +title: Geolocation.watchPosition() +slug: Web/API/Geolocation/watchPosition +translation_of: Web/API/Geolocation/watchPosition +--- +<p>{{ APIref("Geolocation API") }}</p> + +<p><strong><code>Geolocation.watchPosition()</code></strong> 這個方法是用來註冊一個處理的函式，當使用者的裝置位置更新時，這個函式所傳入的回呼函式(callback function) 就會自動被呼叫。你也可以選擇性的定義錯誤時哪些錯誤回呼函式(error callback function) 需要被呼叫。</p> + +<p>這個函式將回傳一組 ID 編號，此編號搭配 {{domxref("Geolocation.clearWatch()")}} 函式，即可停止更新使用者的位置。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><em>id</em> = navigator.geolocation.watchPosition(<em>success[</em>, <em>error[</em>, <em>options]]</em>)</pre> + +<h3 id="參數">參數</h3> + +<dl> + <dt><em>success</em></dt> + <dd>一個回呼函式(callback function) 會被傳入一個 {{domxref("Position")}} 的物件。</dd> + <dt><em>error</em> {{optional_inline}}</dt> + <dd>一個選擇性的錯誤回呼函式(callback function)，會被傳入一個{{domxref("PositionError")}} 的物件。</dd> + <dt><em>options</em> {{optional_inline}}</dt> + <dd>一個選擇性 {{domxref("PositionOptions")}} 的物件。</dd> +</dl> + +<h2 id="範例">範例</h2> + +<pre class="brush: js">var id, target, options; + +function success(pos) { + var crd = pos.coords; + + if (target.latitude === crd.latitude && target.longitude === crd.longitude) { + console.log('Congratulations, you reached the target'); + navigator.geolocation.clearWatch(id); + } +} + +function error(err) { + console.warn('ERROR(' + err.code + '): ' + err.message); +} + +target = { + latitude : 0, + longitude: 0 +}; + +options = { + enableHighAccuracy: false, + timeout: 5000, + maximumAge: 0 +}; + +id = navigator.geolocation.watchPosition(success, error, options); +</pre> + +<h2 id="備註">備註</h2> + +<p>如果你的應用程式是跑在 firefox OS上，請參考 <a href="/en-US/docs/Web/API/Geolocation/navigator.requestWakeLock()">geolocation wake lock</a>，此方法可以讓你的程式在背景或螢幕關上時也能持續收到位置更新。</p> + +<h2 id="規格">規格</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('Geolocation', '#watch-position', 'Geolocation.watchPosition()')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + Removed in 15.0<br> + Reintroduced in 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown()}}</td> + <td>{{CompatUnknown()}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown()}}</td> + <td>10.60</td> + <td>{{CompatUnknown()}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/Geolocation/navigator.requestWakeLock()">geolocation wake lock</a></li> + <li><a href="/en-US/docs/WebAPI/Using_geolocation" title="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>這個介面屬於{{domxref("Geolocation")}}. 並且存取他的方式為{{domxref("NavigatorGeolocation.geolocation")}}.</li> + <li>相反的操作: {{domxref("Geolocation.clearWatch()")}}</li> + <li>類似的方法: {{domxref("Geolocation.getCurrentPosition()")}}</li> +</ul> diff --git a/files/zh-tw/web/api/geolocationcoordinates/accuracy/index.html b/files/zh-tw/web/api/geolocationcoordinates/accuracy/index.html new file mode 100644 index 0000000000..4670394148 --- /dev/null +++ b/files/zh-tw/web/api/geolocationcoordinates/accuracy/index.html @@ -0,0 +1,93 @@ +--- +title: Coordinates.accuracy +slug: Web/API/GeolocationCoordinates/accuracy +translation_of: Web/API/GeolocationCoordinates/accuracy +--- +<div>{{APIRef("Geolocation API")}}</div> + +<p><code><strong>Coordinates.accuracy</strong></code> 是個唯讀的正複數用來代表 {{domxref("Coordinates.latitude")}} 和 {{domxref("Coordinates.longitude")}} 的準確度，單位為公尺，並有 95% 可靠度。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><var>acc</var> = <var>coordinates</var>.accuracy +</pre> + +<h2 id="規格">規格</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('Geolocation', '#accuracy', 'Coordinates.accuracy')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + {{CompatNo}} 15.0<br> + 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown}}</td> + <td>10.60</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>屬於 {{domxref("Coordinates")}} 介面。</li> +</ul> diff --git a/files/zh-tw/web/api/geolocationcoordinates/altitude/index.html b/files/zh-tw/web/api/geolocationcoordinates/altitude/index.html new file mode 100644 index 0000000000..a9e2141793 --- /dev/null +++ b/files/zh-tw/web/api/geolocationcoordinates/altitude/index.html @@ -0,0 +1,93 @@ +--- +title: Coordinates.altitude +slug: Web/API/GeolocationCoordinates/altitude +translation_of: Web/API/GeolocationCoordinates/altitude +--- +<div>{{APIRef("Geolocation API")}}</div> + +<p><code><strong>Coordinates.altitude</strong></code> 是個唯讀的正複數用來代表距離海平面的高度，單位為公尺。如果無法提供這個值則回傳 null。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><em>alt</em> = <code><em>coordinates</em><code>.altitude</code></code> +</pre> + +<h2 id="規格">規格</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('Geolocation', '#altitude', 'Coordinates.altitude')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + {{CompatNo}} 15.0<br> + 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown}}</td> + <td>10.60</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>屬於 {{domxref("Coordinates")}} 介面。</li> +</ul> diff --git a/files/zh-tw/web/api/geolocationcoordinates/altitudeaccuracy/index.html b/files/zh-tw/web/api/geolocationcoordinates/altitudeaccuracy/index.html new file mode 100644 index 0000000000..e0ad663ba0 --- /dev/null +++ b/files/zh-tw/web/api/geolocationcoordinates/altitudeaccuracy/index.html @@ -0,0 +1,93 @@ +--- +title: Coordinates.altitudeAccuracy +slug: Web/API/GeolocationCoordinates/altitudeAccuracy +translation_of: Web/API/GeolocationCoordinates/altitudeAccuracy +--- +<div>{{APIRef("Geolocation API")}}</div> + +<p><code><strong>Coordinates.altitudeAccuracy</strong></code> 是個唯讀的正複數用來代表高度的精準度，單位為公尺，並有 95% 可靠度。如果裝置無法提供這個值則回傳 null。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><var>altAcc</var> = <var>coordinates</var>.altitudeAccuracy +</pre> + +<h2 id="規格">規格</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('Geolocation', '#altitudeaccuracy', 'Coordinates.altitudeAccuracy')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + {{CompatNo}} 15.0<br> + 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown}}</td> + <td>10.60</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>屬於 {{domxref("Coordinates")}} 介面。</li> +</ul> diff --git a/files/zh-tw/web/api/geolocationcoordinates/heading/index.html b/files/zh-tw/web/api/geolocationcoordinates/heading/index.html new file mode 100644 index 0000000000..be762eb369 --- /dev/null +++ b/files/zh-tw/web/api/geolocationcoordinates/heading/index.html @@ -0,0 +1,93 @@ +--- +title: Coordinates.heading +slug: Web/API/GeolocationCoordinates/heading +translation_of: Web/API/GeolocationCoordinates/heading +--- +<div>{{APIRef("Geolocation API")}}</div> + +<p><code><strong>Coordinates.heading</strong></code> 是個唯讀的正複數用來代表裝置前進的方向。這個數值代表你偏離北方多少度，0度代表你向著正北方，照著順時針的方向遞增(90度代表正東方，270度代表正西方)。如果{{domxref("Coordinates.speed")}} 為0度，則此值為 <code><a href="https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/NaN" title="/en-US/docs/JavaScript/Reference/Global_Objects/NaN">NaN</a></code>。如果這個裝置無法提供這個值則回傳 null。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><var>heading</var> = <var>coordinates</var>.heading +</pre> + +<h2 id="規格">規格</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('Geolocation', '#heading', 'Coordinates.heading')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + {{CompatNo}} 15.0<br> + 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown}}</td> + <td>10.60</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>屬於 {{domxref("Coordinates")}} 介面。</li> +</ul> diff --git a/files/zh-tw/web/api/geolocationcoordinates/index.html b/files/zh-tw/web/api/geolocationcoordinates/index.html new file mode 100644 index 0000000000..08be554dff --- /dev/null +++ b/files/zh-tw/web/api/geolocationcoordinates/index.html @@ -0,0 +1,113 @@ +--- +title: Coordinates +slug: Web/API/GeolocationCoordinates +translation_of: Web/API/GeolocationCoordinates +--- +<div>{{APIRef("Geolocation API")}}</div> + +<p><strong><code>Coordinates </code></strong><code>這個介面用來存取裝置的經緯度</code>，速度以及這些數值的準確度。</p> + +<h2 id="屬性">屬性</h2> + +<p><em><code>Coordinates</code> 這個介面沒有繼承任何屬性</em>。</p> + +<dl> + <dt>{{domxref("Coordinates.latitude")}} {{readonlyInline}}</dt> + <dd>回傳一個十進位的 double 代表緯度。</dd> + <dt>{{domxref("Coordinates.longitude")}} {{readonlyInline}}</dt> + <dd>回傳一個十進位的 double 代表經度。</dd> + <dt>{{domxref("Coordinates.altitude")}} {{readonlyInline}}</dt> + <dd>回傳一個 double 代表距離海平面的高度，單位為公尺。如果無法提供這個值則回傳 null。</dd> + <dt>{{domxref("Coordinates.accuracy")}} {{readonlyInline}}</dt> + <dd>回傳一個 double 代表經緯度的精準值，單位為公尺。</dd> + <dt>{{domxref("Coordinates.altitudeAccuracy")}} {{readonlyInline}}</dt> + <dd>回傳一個 double 代表高度的精準度，單位為公尺。如果無法提供這個值則回傳 null。</dd> + <dt>{{domxref("Coordinates.heading")}} {{readonlyInline}}</dt> + <dd>回傳一個 double 代表裝置前進的方向，這個數值代表你偏離北方多少度，0度代表你向著正北方，照著順時針的方向遞增(90度代表正東方，270度代表正西方) 。如果速度值為0度，則此值為 <code><a href="/en-US/docs/JavaScript/Reference/Global_Objects/NaN" title="/en-US/docs/JavaScript/Reference/Global_Objects/NaN">NaN</a></code>。如果無法提供這個值則回傳 null。</dd> + <dt>{{domxref("Coordinates.speed")}} {{readonlyInline}}</dt> + <dd>回傳一個 double 代表速度，單位為公尺/秒。如果無法提供這個值則回傳 null。</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em><em><code>Coordinates</code> 這個介面</em></em>，沒有實作也沒有繼承自任何的方法。<em><em> </em></em></p> + +<h2 id="規格">規格</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('Geolocation', '#coordinates', 'Coordinates')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + {{CompatNo}} 15.0<br> + 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown()}}</td> + <td>{{CompatUnknown()}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown()}}</td> + <td>10.60</td> + <td>{{CompatUnknown()}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation" title="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>{{domxref("Geolocation")}} 介面使用此物件。</li> +</ul> diff --git a/files/zh-tw/web/api/geolocationcoordinates/latitude/index.html b/files/zh-tw/web/api/geolocationcoordinates/latitude/index.html new file mode 100644 index 0000000000..18c43451f2 --- /dev/null +++ b/files/zh-tw/web/api/geolocationcoordinates/latitude/index.html @@ -0,0 +1,93 @@ +--- +title: Coordinates.latitude +slug: Web/API/GeolocationCoordinates/latitude +translation_of: Web/API/GeolocationCoordinates/latitude +--- +<div>{{APIRef("Geolocation API")}}</div> + +<p><code><strong>Coordinates.latitude</strong></code> 是個唯讀十進位的複數用來代表裝置緯度的位置。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><em>lat</em> = <code><em>coordinates</em><code>.latitude</code></code> +</pre> + +<h2 id="規格">規格</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('Geolocation', '#lat', 'Coordinates.latitude')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + {{CompatNo}} 15.0<br> + 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown}}</td> + <td>10.60</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>屬於 {{domxref("Coordinates")}} 介面。</li> +</ul> diff --git a/files/zh-tw/web/api/geolocationcoordinates/longitude/index.html b/files/zh-tw/web/api/geolocationcoordinates/longitude/index.html new file mode 100644 index 0000000000..f5625d20c6 --- /dev/null +++ b/files/zh-tw/web/api/geolocationcoordinates/longitude/index.html @@ -0,0 +1,93 @@ +--- +title: Coordinates.longitude +slug: Web/API/GeolocationCoordinates/longitude +translation_of: Web/API/GeolocationCoordinates/longitude +--- +<div>{{APIRef("Geolocation API")}}</div> + +<p><code><strong>Coordinates.longitude</strong></code> 是個唯讀十進位的複數用來代表裝置經度的位置。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><var>lon</var> = <var>coordinates</var>.longitude +</pre> + +<h2 id="規格">規格</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('Geolocation', '#lon', 'Coordinates.longitude')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + {{CompatNo}} 15.0<br> + 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown}}</td> + <td>10.60</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>屬於{{domxref("Coordinates")}} 介面。</li> +</ul> diff --git a/files/zh-tw/web/api/geolocationcoordinates/speed/index.html b/files/zh-tw/web/api/geolocationcoordinates/speed/index.html new file mode 100644 index 0000000000..74c1940232 --- /dev/null +++ b/files/zh-tw/web/api/geolocationcoordinates/speed/index.html @@ -0,0 +1,93 @@ +--- +title: Coordinates.speed +slug: Web/API/GeolocationCoordinates/speed +translation_of: Web/API/GeolocationCoordinates/speed +--- +<div>{{APIRef("Geolocation API")}}</div> + +<p><code><strong>Coordinates.speed</strong></code> 回傳唯讀的正複數代表速度，單位為公尺/秒。 如果裝置無法測量這個值則回傳 null。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><var>speed</var> = <var>coordinates</var>.speed +</pre> + +<h2 id="規格">規格</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('Geolocation', '#speed', 'Coordinates.speed')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + {{CompatNo}} 15.0<br> + 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown}}</td> + <td>10.60</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>屬於 {{domxref("Coordinates")}} 介面。</li> +</ul> diff --git a/files/zh-tw/web/api/geolocationposition/coords/index.html b/files/zh-tw/web/api/geolocationposition/coords/index.html new file mode 100644 index 0000000000..c6e018c8cc --- /dev/null +++ b/files/zh-tw/web/api/geolocationposition/coords/index.html @@ -0,0 +1,93 @@ +--- +title: Position.coords +slug: Web/API/GeolocationPosition/coords +translation_of: Web/API/GeolocationPosition/coords +--- +<div>{{APIRef("Geolocation API")}}</div> + +<p><code><strong>Position.coords</strong></code> 是一個 {{domxref("Coordinates")}} 物件的唯讀屬性，表示地理的特性：回傳的物件中包括位置、地球經緯度、海拔高度和速度，同時也包含著這些值的精準度訊息。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><var>coord</var> = <var>position</var>.coords +</pre> + +<h2 id="規格">規格</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('Geolocation', '#coords', 'Position.coords')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + {{CompatNo}} 15.0<br> + 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown}}</td> + <td>10.60</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>屬於 {{domxref("Position")}}。</li> +</ul> diff --git a/files/zh-tw/web/api/geolocationposition/index.html b/files/zh-tw/web/api/geolocationposition/index.html new file mode 100644 index 0000000000..ecf342ff49 --- /dev/null +++ b/files/zh-tw/web/api/geolocationposition/index.html @@ -0,0 +1,103 @@ +--- +title: Position +slug: Web/API/GeolocationPosition +translation_of: Web/API/GeolocationPosition +--- +<div>{{APIRef("Geolocation API")}}</div> + +<p><strong><code>Position</code></strong> 介面表示在給定時間相關裝置的位置。這個位置用一個 {{domxref("Coordinates")}} 物件表示，包括裝置在地球上的二維位置，以及裝置的海拔高度和速度。</p> + +<h2 id="屬性">屬性</h2> + +<p><em><code>Position</code> 介面沒有繼承任何屬性</em></p> + +<dl> + <dt>{{domxref("Position.coords")}} {{readonlyInline}}</dt> + <dd>回傳一個定義當前位置的 {{domxref("Coordinates")}} 物件。</dd> + <dt>{{domxref("Position.timestamp")}} {{readonlyInline}}</dt> + <dd>回傳一個時間戳 {{domxref("DOMTimeStamp")}} ，這個時間戳表示獲取到位置的時間。</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em><em><code>Position 介面沒有實作或繼承任何方法</code> </em></em></p> + +<h2 id="規格">規格</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('Geolocation', '#position', 'Position')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + {{CompatNo}} 15.0<br> + 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown}}</td> + <td>10.60</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>{{domxref("Geolocation")}} 介面使用此物件。</li> +</ul> diff --git a/files/zh-tw/web/api/geolocationposition/timestamp/index.html b/files/zh-tw/web/api/geolocationposition/timestamp/index.html new file mode 100644 index 0000000000..26c72e5e14 --- /dev/null +++ b/files/zh-tw/web/api/geolocationposition/timestamp/index.html @@ -0,0 +1,93 @@ +--- +title: Position.timestamp +slug: Web/API/GeolocationPosition/timestamp +translation_of: Web/API/GeolocationPosition/timestamp +--- +<div>{{APIRef("Geolocation API")}}</div> + +<p><code><strong>Position.timestamp</strong></code> 是一個唯讀的 {{domxref("DOMTimeStamp")}} 物件, 此物件代表建立 {{domxref("Position")}} 物件的日期和時間，精確度為毫秒。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><em>coord</em> = <code><em>position</em><code>.timestamp</code></code> +</pre> + +<h2 id="規格">規格</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('Geolocation', '#timestamp', 'Position.timestamp')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + {{CompatNo}} 15.0<br> + 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown}}</td> + <td>10.60</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>屬於 {{domxref("Position")}}。</li> +</ul> diff --git a/files/zh-tw/web/api/geolocationpositionerror/code/index.html b/files/zh-tw/web/api/geolocationpositionerror/code/index.html new file mode 100644 index 0000000000..e561a780d0 --- /dev/null +++ b/files/zh-tw/web/api/geolocationpositionerror/code/index.html @@ -0,0 +1,120 @@ +--- +title: PositionError.code +slug: Web/API/GeolocationPositionError/code +translation_of: Web/API/GeolocationPositionError/code +--- +<div>{{APIRef("Geolocation API")}}</div> + +<p><code><strong>PositionError.code</strong></code> 是一個唯讀無符號整數(<code>unsigned short)表示錯誤碼</code> 。以下列出可能的值：</p> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">值</th> + <th scope="col">相對應的常數</th> + <th scope="col">描述</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>1</code></td> + <td><code>PERMISSION_DENIED</code></td> + <td>取得地理資訊失敗，因為此頁面沒有獲取地理位置信息的權限。</td> + </tr> + <tr> + <td><code>2</code></td> + <td><code>POSITION_UNAVAILABLE</code></td> + <td>取得地理資訊失敗，因為至少有一個地理位置信息內的資訊回傳了錯誤。</td> + </tr> + <tr> + <td><code>3</code></td> + <td><code>TIMEOUT</code></td> + <td>取得地理資訊超過時限，利用 {{domxref("PositionOptions.timeout")}} i來定義取得地理資訊的時限。</td> + </tr> + </tbody> +</table> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><var>typeErr</var> = <var>poserr</var>.code +</pre> + +<h2 id="規格">規格</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('Geolocation', '#code', 'PositionError.code')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + {{CompatNo}} 15.0<br> + 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown}}</td> + <td>10.60</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>屬於 {{domxref("PositionError")}} 。</li> +</ul> diff --git a/files/zh-tw/web/api/geolocationpositionerror/index.html b/files/zh-tw/web/api/geolocationpositionerror/index.html new file mode 100644 index 0000000000..e721bd062c --- /dev/null +++ b/files/zh-tw/web/api/geolocationpositionerror/index.html @@ -0,0 +1,128 @@ +--- +title: PositionError +slug: Web/API/GeolocationPositionError +translation_of: Web/API/GeolocationPositionError +--- +<div>{{APIRef("Geolocation API")}}</div> + +<p><strong><code>PositionError</code></strong> 介面表示使用定位設備時發生錯誤的原因。</p> + +<h2 id="屬性">屬性</h2> + +<p><em><code>PositionError</code> 介面沒有繼承任何屬性</em>。</p> + +<dl> + <dt>{{domxref("PositionError.code")}} {{readonlyInline}}</dt> + <dd>回傳一個無符號整數<code>(unsigned short</code>)來表示錯誤碼。以下列出可能的值： + <table class="standard-table"> + <tbody> + <tr> + <th scope="col">值</th> + <th scope="col">相對應的常數</th> + <th scope="col">描述</th> + </tr> + <tr> + <td><code>1</code></td> + <td><code>PERMISSION_DENIED</code></td> + <td>取得地理資訊失敗，因為此頁面沒有獲取地理位置信息的權限。</td> + </tr> + <tr> + <td><code>2</code></td> + <td><code>POSITION_UNAVAILABLE</code></td> + <td>取得地理資訊失敗，因為至少有一個地理位置信息內的資訊回傳了錯誤。</td> + </tr> + <tr> + <td><code>3</code></td> + <td><code>TIMEOUT</code></td> + <td>取得地理資訊超過時限，利用{{domxref("PositionOptions.timeout")}} 來定義取得地理資訊的時限。</td> + </tr> + </tbody> + </table> + </dd> + <dt>{{domxref("PositionError.message")}} {{readonlyInline}}</dt> + <dd>回傳一個可讀的 {{domxref("DOMString")}} 來描述錯誤的詳細訊息。注意規格中指出此訊息是用來除錯而非直接顯示在使用者介面。</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em><em><code>PositionError</code> 介面沒有實作也沒有繼承任何方法</em></em>。</p> + +<h2 id="規格">規格</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('Geolocation', '#positionerror', 'PositionError')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + {{CompatNo}} 15.0<br> + 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown}}</td> + <td>10.60</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>{{domxref("Geolocation")}} 介面使用此物件。</li> +</ul> diff --git a/files/zh-tw/web/api/geolocationpositionerror/message/index.html b/files/zh-tw/web/api/geolocationpositionerror/message/index.html new file mode 100644 index 0000000000..839fb18818 --- /dev/null +++ b/files/zh-tw/web/api/geolocationpositionerror/message/index.html @@ -0,0 +1,93 @@ +--- +title: PositionError.message +slug: Web/API/GeolocationPositionError/message +translation_of: Web/API/GeolocationPositionError/message +--- +<div>{{APIRef("Geolocation API")}}</div> + +<p><code><strong>PositionError.message</strong></code> 是一個可讀的 {{domxref("DOMString")}} 來描述錯誤的詳細訊息。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><var>msg</var> = <var>positionError</var>.message +</pre> + +<h2 id="規格">規格</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('Geolocation', '#message', 'PositionError.message')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + {{CompatNo}} 15.0<br> + 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown}}</td> + <td>10.60</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>屬於 {{domxref("PositionError")}}。</li> +</ul> diff --git a/files/zh-tw/web/api/globaleventhandlers/index.html b/files/zh-tw/web/api/globaleventhandlers/index.html new file mode 100644 index 0000000000..492ed0ae93 --- /dev/null +++ b/files/zh-tw/web/api/globaleventhandlers/index.html @@ -0,0 +1,682 @@ +--- +title: GlobalEventHandlers +slug: Web/API/GlobalEventHandlers +translation_of: Web/API/GlobalEventHandlers +--- +<div>{{ApiRef("HTML DOM")}}</div> + +<p><strong><code>GlobalEventHandlers(通用事件處理器)</code></strong>在多個介面，如 {{domxref("HTMLElement")}}、{{domxref("Document")}} 和 {{domxref("Window")}} 當中加入了共有的事件處理器屬性，這些介面皆能夠加入除了以下清單外的更多事件處理器。</p> + +<div class="note"> +<p><strong>Note</strong>: <code>GlobalEventHandlers</code> is a mixin and not an interface; you can't actually create an object of type <code>GlobalEventHandlers</code>.</p> +</div> + +<h2 id="屬性">屬性</h2> + +<p><em>This interface doesn't include any properties except for the event handlers listed below.</em></p> + +<h3 id="事件處理器">事件處理器</h3> + +<p>These event handlers are defined on the {{domxref("GlobalEventHandlers")}} mixin, and implemented by {{domxref("HTMLElement")}}, {{domxref("Document")}}, {{domxref("Window")}}, as well as by {{domxref("WorkerGlobalScope")}} for Web Workers.</p> + +<div id="Properties"> +<dl> + <dt>{{domxref("GlobalEventHandlers.onabort")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("abort")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onanimationcancel")}} {{Non-standard_inline}}</dt> + <dd>An {{domxref("EventHandler")}} called when an {{event("animationcancel")}} event is sent, indicating that a running <a href="/docs/Web/CSS/CSS_Animations">CSS animation</a> has been canceled.</dd> + <dt>{{domxref("GlobalEventHandlers.onanimationend")}} {{Non-standard_inline}}</dt> + <dd>An {{domxref("EventHandler")}} called when an {{event("animationend")}} event is sent, indicating that a <a href="/docs/Web/CSS/CSS_Animations">CSS animation</a> has stopped playing.</dd> + <dt>{{domxref("GlobalEventHandlers.onanimationiteration")}} {{Non-standard_inline}}</dt> + <dd>An {{domxref("EventHandler")}} called when an {{event("animationiteration")}} event has been sent, indicating that a <a href="/docs/Web/CSS/CSS_Animations">CSS animation</a> has begun playing a new iteration of the animation sequence.</dd> + <dt>{{domxref("GlobalEventHandlers.onanimationstart")}} {{Non-standard_inline}}</dt> + <dd>An {{domxref("EventHandler")}} called when an {{event("animationstart")}} event is sent, indicating that a <a href="/docs/Web/CSS/CSS_Animations">CSS animation</a> has started playing.</dd> + <dt>{{domxref("GlobalEventHandlers.onauxclick")}} {{Non-standard_inline}}</dt> + <dd>An {{domxref("EventHandler")}} called when an {{event("auxclick")}} event is sent, indicating that a non-primary button has been pressed on an input device (e.g. a middle mouse button).</dd> + <dt>{{domxref("GlobalEventHandlers.onblur")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("blur")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onerror")}}</dt> + <dd>Is an {{domxref("OnErrorEventHandler")}} representing the code to be called when the {{event("error")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onfocus")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("focus")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.oncancel")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("cancel")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.oncanplay")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("canplay")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.oncanplaythrough")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("canplaythrough")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onchange")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("change")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onclick")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("click")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onclose")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("close")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.oncontextmenu")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("contextmenu")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.oncuechange")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("cuechange")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.ondblclick")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("dblclick")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.ondrag")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("drag")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.ondragend")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("dragend")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.ondragenter")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("dragenter")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.ondragexit")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("dragexit")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.ondragleave")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("dragleave")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.ondragover")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("dragover")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.ondragstart")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("dragstart")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.ondrop")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("drop")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.ondurationchange")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("durationchange")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onemptied")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("emptied")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onended")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("ended")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.ongotpointercapture")}}</dt> + <dd> + <p>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("gotpointercapture")}} event type is raised.</p> + </dd> + <dt>{{domxref("GlobalEventHandlers.oninput")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("input")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.oninvalid")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("invalid")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onkeydown")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("keydown")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onkeypress")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("keypress")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onkeyup")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("keyup")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onload")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("load")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onloadeddata")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("loadeddata")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onloadedmetadata")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("loadedmetadata")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onloadend")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("loadend")}} event is raised (when progress has stopped on the loading of a resource.)</dd> + <dt>{{domxref("GlobalEventHandlers.onloadstart")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("loadstart")}} event is raised (when progress has begun on the loading of a resource.)</dd> + <dt>{{domxref("GlobalEventHandlers.onlostpointercapture")}}</dt> + <dd> + <p>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("lostpointercapture")}} event type is raised.</p> + </dd> + <dt>{{domxref("GlobalEventHandlers.onmousedown")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("mousedown")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onmouseenter")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("mouseenter")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onmouseleave")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("mouseleave")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onmousemove")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("mousemove")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onmouseout")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("mouseout")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onmouseover")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("mouseover")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onmouseup")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("mouseup")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onmousewheel")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("mousewheel")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onpause")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("pause")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onplay")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("play")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onplaying")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("playing")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onpointerdown")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("pointerdown")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onpointermove")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("pointermove")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onpointerup")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("pointerup")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onpointercancel")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("pointercancel")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onpointerover")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("pointerover")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onpointerout")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("pointerout")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onpointerenter")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("pointerevent")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onpointerleave")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("pointerleave")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onpointerlockchange")}} {{experimental_inline}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("pointerlockchange")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onpointerlockerror")}} {{experimental_inline}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("pointerlockerror")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onprogress")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("progress")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onratechange")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("ratechange")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onreset")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("reset")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onscroll")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("scroll")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onseeked")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("seeked")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onseeking")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("seeking")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onselect")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("select")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onselectstart")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("selectionchange")}} event is raised, i.e. when the user starts to make a new text selection on a web page.</dd> + <dt>{{domxref("GlobalEventHandlers.onselectionchange")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("selectionchange")}} event is raised, i.e. when the text selected on a web page changes.</dd> + <dt>{{domxref("GlobalEventHandlers.onshow")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("show")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onsort")}} {{experimental_inline}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("sort")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onstalled")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("stalled")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onsubmit")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("submit")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onsuspend")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("suspend")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.ontimeupdate")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("timeupdate")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onvolumechange")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("volumechange")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.ontouchcancel")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("touchcancel")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.ontouchend")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("touchend")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.ontouchmove")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("touchmove")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.ontouchstart")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("touchstart")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.ontransitioncancel")}}</dt> + <dd>An {{domxref("EventHandler")}} called when a {{event("transitioncancel")}} event is sent, indicating that a <a href="/en-US/docs/Web/CSS/CSS_Transitions">CSS transition</a> has been cancelled.</dd> + <dt>{{domxref("GlobalEventHandlers.ontransitionend")}}</dt> + <dd>An {{domxref("EventHandler")}} called when a {{event("transitionend")}} event is sent, indicating that a <a href="/en-US/docs/Web/CSS/CSS_Transitions">CSS transition</a> has finished playing.</dd> + <dt>{{domxref("GlobalEventHandlers.onwaiting")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("waiting")}} event is raised.</dd> +</dl> +</div> + +<h2 id="方法">方法</h2> + +<p><em>This interface defines no methods.</em></p> + +<h2 id="規範">規範</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("Selection API",'', 'Extension to GlobalEventHandlers')}}</td> + <td>{{Spec2('Selection API')}}</td> + <td>Adds <code>onselectionchange.</code></td> + </tr> + <tr> + <td>{{SpecName('Pointer Lock', '#extensions-to-the-document-interface', 'Extension of Document')}}</td> + <td>{{Spec2('Pointer Lock')}}</td> + <td>Adds <code>onpointerlockchange</code> and <code>onpointerlockerror</code> on {{domxref("Document")}}. It is experimentally implemented on <code>GlobalEventHandlers</code>.</td> + </tr> + <tr> + <td>{{SpecName('HTML WHATWG', '#globaleventhandlers', 'GlobalEventHandlers')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>No change since the latest snapshot, {{SpecName("HTML5.1")}}.</td> + </tr> + <tr> + <td>{{SpecName('HTML5.1', '#globaleventhandlers', 'GlobalEventHandlers')}}</td> + <td>{{Spec2('HTML5.1')}}</td> + <td>Snapshot of {{SpecName("HTML WHATWG")}}. Added <code>onsort</code> since the {{SpecName("HTML5 W3C")}} snapshot.</td> + </tr> + <tr> + <td>{{SpecName("HTML5 W3C", "#globaleventhandlers", "GlobalEventHandlers")}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>Snapshot of {{SpecName("HTML WHATWG")}}. Creation of <code>GlobalEventHandlers</code> (properties where on the target before it).</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Firefox (Gecko)</th> + <th>Chrome</th> + <th>Edge</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>oncanplay</code>, <code>oncanplaythrough</code>, <code>ondurationchange</code>, <code>onemptied</code>, <code>onended</code>, <code>onloadeddata</code>, <code>onloadedmetadata</code>, <code>onloadstart</code>, <code>onpause</code>, <code>onplay</code>, <code>onplaying</code>, <code>onprogress</code>, <code>onratechange</code>, <code>onseeked</code>, <code>onseeking</code>, <code>onstalled</code>, <code>ontimeupdate</code>, <code>onvolumechange</code>, <code>onwaiting</code></td> + <td>{{CompatGeckoDesktop(1.9.1)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>onsuspend</code></td> + <td>{{CompatGeckoDesktop(1.9.2)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>ondrag</code>, <code>ondragend</code>, <code>ondragenter</code>, <code>ondragleave</code>, <code>ondragover</code>, <code>ondragstart</code>, <code>ondrop</code></td> + <td>{{CompatGeckoDesktop(1.9.1)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>onmouseenter</code>, <code>onmouseleave</code></td> + <td>{{CompatGeckoDesktop(10)}}</td> + <td>{{CompatChrome(30.0)}}</td> + <td>{{CompatUnknown}}</td> + <td>5.5</td> + <td>17</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>ondragexit</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>oncancel</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>onclose</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>oncuechange</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>onmousewheel</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>onsort</code> {{experimental_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>onmozfullscreenchange</code>, <code>onmozfullscreenerror</code> {{non-standard_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}} {{property_prefix("-webkit")}}<br> + {{CompatVersionUnknown}} (unprefixed)</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>onpointerlockchange</code>, <code>onpointerlockerror</code></td> + <td>{{CompatGeckoDesktop(10)}}<sup>[1]</sup></td> + <td>{{CompatVersionUnknown}}<sup>[2] </sup>{{property_prefix("-webkit")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>onpointercancel</code>, <code>onpointerdown</code>, <code>onpointerup</code>, <code>onpointermove</code>, <code>onpointerout</code>, <code>onpointerover</code>, <code>onpointerenter</code>, <code>onpointerleave</code></td> + <td>{{CompatVersionUnknown}}<sup>[3]</sup></td> + <td>{{CompatChrome(55.0)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>10</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>onselectionchange</code></td> + <td>{{CompatGeckoDesktop(43)}}<sup>[4]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>ontouchend</code>, <code>ontouchcancel</code>, <code>ontouchmove</code>, <code>ontouchstart</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>animationstart</code>, <code>animationend</code>, <code>animationcancel</code>, <code>animationiteration</code></td> + <td>{{CompatGeckoDesktop(51)}}</td> + <td>{{CompatVersionUnknown}} {{property_prefix("-webkit")}}<br> + {{CompatVersionUnknown}} (unprefixed)</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>ongotpointercapture</code>, <code>onlostpointercapture</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatChrome(57.0)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatOpera(44)}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>onauxclick</code></td> + <td>{{CompatGeckoDesktop(53)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android Webview</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>Android</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>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>ondrag</code>, <code>ondragend</code>, <code>ondragenter</code>, <code>ondragleave</code>, <code>ondragover</code>, <code>ondragstart</code>, <code>ondrop</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile(1.9.1)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>oncanplay</code>, <code>oncanplaythrough</code>, <code>ondurationchange</code>, <code>onemptied</code>, <code>onended</code>, <code>onloadeddata</code>, <code>onloadedmetadata</code>, <code>onloadstart</code>, <code>onpause</code>, <code>onplay</code>, <code>onplaying</code>, <code>onprogress</code>, <code>onratechange</code>, <code>onseeked</code>, <code>onseeking</code>, <code>onstalled</code>, <code>ontimeupdate</code>, <code>onvolumechange</code>, <code>onwaiting</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile(1.9.1)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>onmouseenter</code>, <code>onmouseleave</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile(10)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>onsuspend</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile(1.9.2)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>ondragexit</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>oncancel</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>onclose</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>oncuechange</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>onmousewheel</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>onsort</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>onmozfullscreenchange</code>, <code>onmozfullscreenerror</code> {{non-standard_inline}}</td> + <td>{{CompatVersionUnknown}} {{property_prefix("-webkit")}}<br> + {{CompatVersionUnknown}} (unprefixed)</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}} {{property_prefix("-webkit")}}<br> + {{CompatVersionUnknown}} (unprefixed)</td> + </tr> + <tr> + <td><code>onpointerlockchange</code>, <code>onpointerlockerror</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile(10)}}<sup>[1]</sup></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>onpointercancel</code>, <code>onpointerdown</code>, <code>onpointerup</code>, <code>onpointermove</code>, <code>onpointerout</code>, <code>onpointerover</code>, <code>onpointerenter</code>, <code>onpointerleave</code></td> + <td>{{CompatChrome(55.0)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}<sup>[3]</sup></td> + <td>{{CompatNo}}</td> + <td>10</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatChrome(55.0)}}</td> + </tr> + <tr> + <td><code>onselectionchange</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile(43)}}<sup>[4]</sup></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>ontouchend</code>, <code>ontouchcancel</code>, <code>ontouchmove</code>, <code>ontouchstart</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>animationstart</code>, <code>animationend</code>, <code>animationcancel</code>, <code>animationiteration</code></td> + <td>{{CompatVersionUnknown}} {{property_prefix("-webkit")}}<br> + {{CompatVersionUnknown}} (unprefixed)</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile(51)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}} {{property_prefix("-webkit")}}<br> + {{CompatVersionUnknown}} (unprefixed)</td> + </tr> + <tr> + <td><code>ongotpointercapture</code>, <code>onlostpointercapture</code></td> + <td>{{CompatChrome(57.0)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatOperaMobile(44)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatChrome(57.0)}}</td> + </tr> + <tr> + <td><code>onauxclick</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile(53)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] In Gecko this is implemented as <code>onmozpointerlockchange</code>, <code>onmozpointerlockerror</code>.</p> + +<p>[2] In Blink this is implemented as <code>onwebkitpointerlockchange</code>, <code>onwebkitpointerlockerror</code>.</p> + +<p>[3] This is implemented behind the <code>dom.w3c_pointer_events.enabled</code> preference, defaulting to <code>false</code>.</p> + +<p>[4] This is implemented behind the <code>dom.select_events.enabled</code> preference, that default to <code>false</code>, except on Nightly.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("Element")}}</li> + <li>{{domxref("EventHandler")}}</li> + <li>{{domxref("Event")}}</li> +</ul> diff --git a/files/zh-tw/web/api/globaleventhandlers/onclick/index.html b/files/zh-tw/web/api/globaleventhandlers/onclick/index.html new file mode 100644 index 0000000000..d5a1ac1845 --- /dev/null +++ b/files/zh-tw/web/api/globaleventhandlers/onclick/index.html @@ -0,0 +1,144 @@ +--- +title: GlobalEventHandlers.onclick +slug: Web/API/GlobalEventHandlers/onclick +tags: + - API + - HTML DOM + - Property + - Reference +translation_of: Web/API/GlobalEventHandlers/onclick +--- +<div> +<div>{{ ApiRef("HTML DOM") }}</div> +</div> + +<div> </div> + +<p><strong>onclick</strong> 屬性回傳當前元件 <code>click</code> 事件處理器的程式碼（event handler code）。</p> + +<div class="note"><strong>注意:</strong> 當使用 <code>click</code> 事件觸發動作時，同時考慮將此動作加到 <code>keydown</code> 事件中，讓沒使用滑鼠或使用觸控螢幕的使用者也可以進行此動作。</div> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox"><var>element</var>.onclick = <var>functionRef</var>; +</pre> + +<p>此處的 <em>functionRef</em> 為一個函式－通常是函式的名字或是<em>函式表示式</em>（function expression）<em>。</em> 見 "<a href="/en-US/docs/JavaScript/Guide/Functions">JavaScript Guide:Functions</a>" 來了解更多。</p> + +<p>傳入事件處理函式（event handler function）的唯一引數為 {{domxref("MouseEvent")}} 物件。在這函式中，<code>this</code> 為觸發此事件的元件。</p> + +<h2 id="Example" name="Example">範例</h2> + +<pre class="brush:html"><!DOCTYPE html> +<html lang="en"> + <head> + <meta charset="UTF-8" /> + <title>onclick event example</title> + <script> + function initElement() { + var p = document.getElementById("foo"); + // NOTE: showAlert(); or showAlert(param); will NOT work here. + // Must be a reference to a function name, not a function call. + p.onclick = showAlert; + }; + + function showAlert(event) { + alert("onclick Event detected!"); + } + </script> + <style> + #foo { + border: solid blue 2px; + } + </style> + </head> + <body onload="initElement();"> + <span id="foo">My Event Element</span> + <p>click on the above element.</p> + </body> +</html> +</pre> + +<p>你也可以使用如下的匿名函式：</p> + +<pre class="brush:js">p.onclick = function(event) { alert("moot!"); }; +</pre> + +<h2 id="Notes" name="Notes">備註</h2> + +<p>使用者點擊元件時會觸發 <code>click</code> 事件。<code>click</code> 事件發生在 <code>mousedown</code> 及 <code>mouseup</code> 事件之後。</p> + +<p>這個屬性同一時間中只能指定一個 <code>click</code> 處理器（handler）。你也許會比較想使用 {{domxref("EventTarget.addEventListener()")}}，因為它有更多的彈性而且是 DOM 事件規範的一部份。</p> + +<h2 id="Specification" name="Specification">規範</h2> + +<table class="spectable standard-table"> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">備註</th> + </tr> + <tr> + <td>{{SpecName('HTML WHATWG','webappapis.html#handler-onclick','onclick')}}</td> + <td>{{Spec2('HTML WHATWG')}}</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</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>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> diff --git a/files/zh-tw/web/api/globaleventhandlers/onclose/index.html b/files/zh-tw/web/api/globaleventhandlers/onclose/index.html new file mode 100644 index 0000000000..abe97bcd4c --- /dev/null +++ b/files/zh-tw/web/api/globaleventhandlers/onclose/index.html @@ -0,0 +1,102 @@ +--- +title: GlobalEventHandlers.onclose +slug: Web/API/GlobalEventHandlers/onclose +tags: + - API + - HTML DOM + - Property + - Reference +translation_of: Web/API/GlobalEventHandlers/onclose +--- +<div>{{ApiRef("HTML DOM")}}</div> + +<p>送至視窗的 close event 的處理器（handler）。（不支援 Firefox 2 及 Safari）</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">window.onclose = funcRef; +</pre> + +<h3 id="參數">參數</h3> + +<ul> + <li><code>funcRef</code> 為函式的參照。</li> +</ul> + +<h2 id="範例">範例</h2> + +<pre class="brush: js">window.onclose = resetThatServerThing; +</pre> + +<h2 id="規範">規範</h2> + +<table class="spectable standard-table"> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">備註</th> + </tr> + <tr> + <td>{{SpecName('HTML WHATWG','webappapis.html#handler-onclose','onclose')}}</td> + <td>{{Spec2('HTML WHATWG')}}</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</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>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> diff --git a/files/zh-tw/web/api/history/index.html b/files/zh-tw/web/api/history/index.html new file mode 100644 index 0000000000..b4a1d7603e --- /dev/null +++ b/files/zh-tw/web/api/history/index.html @@ -0,0 +1,183 @@ +--- +title: History +slug: Web/API/History +translation_of: Web/API/History +--- +<div>{{ APIRef("HTML DOM") }}</div> + +<p><strong><code>History</code></strong> 介面允許操控瀏覽器的 <em>session history</em> 紀錄，為當前面頁所在分頁中訪問、或於當前面頁中透過頁面框架（frame）所載入的頁面。</p> + +<h2 id="屬性">屬性</h2> + +<p><em>The <code>History</code></em><em> interface doesn't inherit any property.</em></p> + +<dl> + <dt>{{domxref("History.length")}} {{readOnlyInline}}</dt> + <dd>Returns an <code>Integer</code> representing the number of elements in the session history, including the currently loaded page. For example, for a page loaded in a new tab this property returns <code>1</code>.</dd> + <dt>{{domxref("History.current")}} {{readOnlyInline}} {{ non-standard_inline() }} {{ obsolete_inline(26) }}</dt> + <dd>Returns a {{domxref("DOMString")}} representing the URL of the active item of the session history. This property was never available to web content and is no more supported by any browser. Use {{domxref("Location.href")}} instead.</dd> + <dt>{{domxref("History.next")}} {{readOnlyInline}} {{ non-standard_inline() }} {{ obsolete_inline(26) }}</dt> + <dd>Returns a {{domxref("DOMString")}} representing the URL of the next item in the session history. This property was never available to web content and is not supported by other browsers.</dd> + <dt>{{domxref("History.previous")}} {{readOnlyInline}} {{ non-standard_inline() }} {{ obsolete_inline(26) }}</dt> + <dd>Returns a {{domxref("DOMString")}} representing the URL of the previous item in the session history. This property was never available to web content and is not supported by other browsers.</dd> + <dt>{{domxref("History.scrollRestoration")}} {{experimental_inline}}</dt> + <dd>Allows web applications to explicitly set default scroll restoration behavior on history navigation. This property can be either <code>auto</code> or <code>manual</code>.</dd> + <dt>{{domxref("History.state")}} {{readOnlyInline}} {{ gecko_minversion_inline("2.0") }}</dt> + <dd>Returns an <code>any</code> value representing the state at the top of the history stack. This is a way to look at the state without having to wait for a {{event("popstate")}} event.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>The <code>History</code></em> <em>interface doesn't inherit any methods.</em></p> + +<dl> + <dt>{{domxref("History.back()")}}</dt> + <dd>回到 session history 紀錄中的前一頁，等同於使用者按下瀏覽器的上一頁按鈕。相當於 <code>history.go(-1)</code>。 + <div class="note">Calling this method to go back beyond the first page in the session history has no effect and doesn't raise an exception.</div> + </dd> + <dt>{{domxref("History.forward()")}}</dt> + <dd>回到 session history 紀錄中的下一頁，等同於使用者按下瀏覽器的下一頁按鈕。相當於 <code>history.go(1)</code>。 + <div class="note">Calling this method to go forward beyond the most recent page in the session history has no effect and doesn't raise an exception.</div> + </dd> + <dt>{{domxref("History.go()")}}</dt> + <dd>自 session history 紀錄中載入一個頁面，利用該頁面相對於目前頁面的所在位置，例如 -1 為前一頁或 1 為下一頁。若指定了一個超出範圍的值（舉例來說，在 session history 沒有先前訪頁面的情況下指定 -1），此方法將會是靜默（不會產生錯誤）且沒有任何效果的。不帶參數或是傳入 0 呼叫 <code>go()</code> 會重新載入目前頁面。Internet Explorer <a href="http://msdn.microsoft.com/en-us/library/ms536443(VS.85).aspx">也可以傳入字串</a>來前往一個於瀏覽歷史列表中指定的頁面。</dd> + <dt>{{domxref("History.pushState()")}} {{ gecko_minversion_inline("2.0") }}</dt> + <dd>插入給定的資料與指定的標題（title）以及選擇性的 URL 至 session history 堆疊（stack）中。給定的資料將被 DOM 視為不透明的（opaque）；可以指定任何可被序列化的 JavaScript 物件。請注意 Firefox 目前會忽略標題（title）參數；更多資訊請參閱<a href="/zh-TW/docs/Web/API/History_API">操控瀏覽器歷史紀錄</a>。</dd> + <dt>{{domxref("History.replaceState()")}} {{ gecko_minversion_inline("2.0") }}</dt> + <dd>以指定的資料、標題（title）及可選的 URL 來更新歷史紀錄堆疊（history stack）中近期的項目。給定的資料將被 DOM 視為不透明的（opaque）；可以指定任何可被序列化的 JavaScript 物件。請注意 Firefox 目前會忽略標題（title）參數；更多資訊請參閱<a href="/zh-TW/docs/Web/API/History_API">操控瀏覽器歷史紀錄</a>。</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('HTML WHATWG', "browsers.html#the-history-interface", "History")}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>Adds the <code>scrollRestoration</code> attribute.</td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', "browsers.html#the-history-interface", "History")}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>Initial definition.</td> + </tr> + <tr> + <td>{{SpecName('Custom Scroll Restoration', '#web-idl', "History")}}</td> + <td>{{Spec2('Custom Scroll Restoration')}}</td> + <td>Adds the <code>scrollRestoration</code> attribute.</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>pushState</code> and <code>replaceState</code></td> + <td>{{CompatChrome(5.0)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>4.0 <sup>[1]</sup></td> + <td>10</td> + <td>11.5</td> + <td>5</td> + </tr> + <tr> + <td><code>scrollRestoration</code></td> + <td>{{CompatChrome(46.0)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop("46.0")}}</td> + <td>{{CompatNo}}</td> + <td>33</td> + <td>{{CompatVersionUnknown}}<sup>[2]</sup></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>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + <th>Chrome for Android</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>pushState</code> and <code>replaceState</code></td> + <td>2.2</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>10</td> + <td>{{CompatVersionUnknown}}</td> + <td>4.3</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>scrollRestoration</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatChrome(46.0)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}<sup>[2]</sup></td> + <td>{{CompatChrome(46.0)}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] In Firefox 2 through 5, the passed object is serialized using JSON. Starting in Firefox 6, the object is serialized using <a href="/en/DOM/The_structured_clone_algorithm" title="en/DOM/The structured clone algorithm">the structured clone algorithm</a>. This allows a wider variety of objects to be safely passed.</p> + +<p>[2] WebKit <a href="https://trac.webkit.org/changeset/213590/webkit">bug 147782</a></p> + +<h2 id="參見">參見</h2> + +<ul> + <li>The {{domxref("Window.history")}} property returning the history of the current session.</li> +</ul> diff --git a/files/zh-tw/web/api/history_api/index.html b/files/zh-tw/web/api/history_api/index.html new file mode 100644 index 0000000000..2554fe6801 --- /dev/null +++ b/files/zh-tw/web/api/history_api/index.html @@ -0,0 +1,255 @@ +--- +title: 操控瀏覽器歷史紀錄 +slug: Web/API/History_API +tags: + - DOM + - HTML5 + - History +translation_of: Web/API/History_API +--- +<p>DOM {{ domxref("window") }} 物件透過 {{ domxref("window.history", "history") }} 物件，提供了進入瀏覽歷史的方式。他透過一些方便的屬性與方法，讓你可以在歷史紀錄中往上一步或往下一步移動，並且讓你——從 HTML5 開始——能操作歷史紀錄堆疊（history stack）的內容。</p> + +<h2 id="在歷史紀錄中移動">在歷史紀錄中移動</h2> + +<p>往前往後歷史紀錄可以用 <code>back()</code>, <code>forward()</code>, 和 <code>go()</code> 的方法。</p> + +<h3 id="往前往後">往前往後</h3> + +<p>要在歷史紀錄中往上一步移動，可以：</p> + +<pre class="brush: js">window.history.back(); +</pre> + +<p>這完全等同於用戶在瀏覽器上點選「上一頁」按鈕。</p> + +<p>同樣的，你也可以往下一步移動（等同於用戶點擊往後一頁的按鈕）：</p> + +<pre class="brush: js">window.history.forward(); +</pre> + +<h3 id="移動到特定的歷史紀錄">移動到特定的歷史紀錄</h3> + +<p>你可以用 <code>go()</code> 方法來從頁面的 session history 紀錄中載入特定紀錄，以目前頁面的相對位置而定（目前的頁面想當然爾是 index 0）。</p> + +<p>往前一頁（等同於呼叫 <code>back()</code>）：</p> + +<pre class="brush: js">window.history.go(-1); +</pre> + +<p>往後一頁（等同於呼叫 <code>forward()</code>）：</p> + +<pre class="brush: js">window.history.go(1); +</pre> + +<p>同樣的你也可以傳入 2，讓頁面直往後兩頁，依此類推。</p> + +<p>你可以查看 length 這個屬性來取得目前瀏覽歷史的總數我：</p> + +<pre class="brush: js">var numberOfEntries = window.history.length; +</pre> + +<div class="note"><strong>備註：</strong>Internet Explorer 支援在 <code>go()</code> 中以 URL 的值作為參數；這不在標準中，Gecko 也不支援。</div> + +<h2 id="加入和修改歷史紀錄">加入和修改歷史紀錄</h2> + +<p>{{ gecko_minversion_header("2") }}</p> + +<p>HTML5 加入了 <a href="/zh-TW/docs/Web/API/History/pushState"><code>history.pushState()</code></a> 和 <a href="/zh-TW/docs/Web/API/History_API#The_replaceState()_method"><code>history.replaceState()</code></a> 方法，讓你可以加入或修改歷史紀錄。這些方法都可以跟 {{ domxref("window.onpopstate") }} 事件一同應用。</p> + +<p>使用 <code>history.pushState()</code>後，會改變 <a href="/zh-TW/docs/Web/API/XMLHttpRequest"><code>XMLHttpRequest</code></a> 時 HTTP 標頭中 referrer 的值。referrer 會是創造 <a href="/zh-TW/docs/Web/API/XMLHttpRequest"><code>XMLHttpRequest</code></a> 物件時的當前視窗文件（<code>this</code>）的 URL。</p> + +<h3 id="pushState()_方法範例">pushState() 方法範例</h3> + +<p>假設 <span class="nowiki">http://mozilla.org/foo.html</span> 執行了下面的 JavaScript：</p> + +<pre class="brush: js">var stateObj = { foo: "bar" }; +history.pushState(stateObj, "page 2", "bar.html"); +</pre> + +<p>這會讓網址列顯示 <span class="nowiki">http://mozilla.org/bar.html</span>，但不會讓瀏覽器去載入 <code>bar.html</code>，甚或去檢查 <code>bar.html</code> 存在與否。</p> + +<p>假設現在使用者瀏覽到 <span class="nowiki">http://google.com</span>，然後點擊上一頁鈕。這時網址列會顯示 <span class="nowiki">http://mozilla.org/bar.html</span>，頁面會獲得 <code>popstate</code> 的事件（<em>state object</em> 會包含一份 <code>stateObj</code> 的副件）。頁面長得跟 <code>foo.html</code> 很像，但是可能在 <code>popstate</code> 事件執行中被修改。</p> + +<p>如果我再點一次上一頁鈕， 網址會改變成為 <span class="nowiki">http://mozilla.org/foo.html</span>，且文件會得到另外一個 <code>popstate</code> 事件，此次會包含一個 null state object。同樣的，回上頁鈕不會改變文件的內容，只是文件可能會在 <code>popstate</code> 事件中被手動更新。</p> + +<h3 id="pushState()_方法">pushState() 方法</h3> + +<p><code>pushState()</code> 取用三個參數：一個 state 物件、title（目前忽略）與 URL（可選用）。我們來看看三個參數的細節之處：</p> + +<ul> + <li> + <p><strong>state object</strong>——state object 是與 <code>pushState()</code> 建立的新瀏覽歷史紀錄有關的一個 JavaScript 物件。只要使用者到了新的 state ，一個 <code>popstate</code> 的事件就會被觸發，然後該事件的 <code>state</code> 屬性會包含一個複製的歷史紀錄的 state object。</p> + + <p>state 物件可以是任何可序列化的東西。因為 Firefox 儲存 state 物件到使用者的硬碟，當瀏覽器被重新啟動的時候，他們是可以被恢復的，因此我們加上了 640k 個字元的長度限制在一個以序列化表示的 state object。如果你傳送一個比這個更大的序列化表示的 state object 到 <code>pushState()</code>，這個方法會丟出一個例外事件。如果你需要更多空間的話，你可以試著用 <code>sessionStorage</code> 和／或 <code>localStorage</code>。</p> + </li> + <li> + <p><strong>title</strong>——Firefox 目前忽略了這個參數，雖然他以後有可能會採用。如果以後改變了這個作法，傳送空白的字串應該還會是安全的。另外，你可以傳送一個短的標題來敘述你想要到的 state。</p> + </li> + <li> + <p><strong>URL</strong>——這個新歷史紀錄的 URL 從這個參數做設定。值得注意的是，在 <code>pushState()</code> 被呼叫之後，瀏覽器並不會馬上嘗試載入這個 URL ，但是它可能在以後嘗試載入這個 URL ，例如使用者重新開啟瀏覽器之後。新的 URL 不一定需要為一個絕對的路徑；如果是相對路徑，會依據目前的URL來解析。新的 URL 需要與目前 URL 的 origin 是一樣的；否則，pushState() 會丟出一個錯誤的例外。這個參數是選擇性的；如果沒有被指定的話，他會設定為目前文件的 URL。</p> + </li> +</ul> + +<div class="note"><strong>備註：</strong>在 Gecko 2.0 {{ geckoRelease("2.0") }} 到 Gecko 5.0 {{ geckoRelease("5.0") }}，是採用 JSON 來序列化這個傳送的物件。從 Gecko 6.0 {{ geckoRelease("6.0") }} 開始,這個物件是以 <a href="/zh-TW/DOM/The_structured_clone_algorithm">the structured clone algorithm</a> 序列化。這會允許更多種不同的物件可以被安全的傳送。</div> + +<p>從某種意義上，呼叫 <code>pushState()</code> 與設定 <code>window.location = "#foo"</code> 是類似的，兩個都會去建立和啟用另一個和目前文件有關的歷史紀錄。但是 <code>pushState()</code> 有一些優勢：</p> + +<ul> + <li>新的 URL 可以是任何一個與目前的 URL 在同一個 origin 的 URL。相對來說，只有你設定 <code>window.location</code> 只修改 hash 時，才讓你保持在同一個 {{ domxref("document") }} 。</li> + <li>如果你不想要的話，你可以不必去改變 URL 。相對來說，設定 <code>window.location = "#foo";</code> 只有在目前的 hash 不是 <code>#foo</code> 的時候，會建立一個新的歷史紀錄。</li> + <li>你可以將任意的資料與你的新的歷史紀錄做關聯。用 hash-based 的方法，你需要將所有相關的資料編碼成一個短字串。</li> + <li>If <code>title </code>is subsequently used by browsers, this data can be utilized (independent of, say, the hash).</li> +</ul> + +<p>注意 <code>pushState()</code> 永遠不會造成一個 <code>hashchange</code> 事件被觸發，即使新的 URL 和舊的 URL 的不同處只有 hash 的部份也不會。</p> + +<p>In a <a href="/en-US/docs/Mozilla/Tech/XUL">XUL</a> document, it creates the specified XUL element.</p> + +<p>In other documents, it creates an element with a <code>null</code> namespace URI.</p> + +<h3 id="replaceState()_方法">replaceState() 方法</h3> + +<p><code>history.replaceState()</code> 的執行就像 <code>history.pushState()</code> ，除了 <code>replaceState() </code>是修改目前的歷史紀錄而不是創造一個新的。</p> + +<p><code>replaceState() </code>很實用的時機是當你要更新目前歷史紀錄的 state object 或是URL來反應一些使用者的動作時。</p> + +<div class="note"><strong>備註：</strong>在 Gecko 2.0 {{ geckoRelease("2.0") }} 到 Gecko 5.0 {{ geckoRelease("5.0") }}，是採用 JSON 來序列化這個傳送的物件。從 Gecko 6.0 {{ geckoRelease("6.0") }} 開始, 這個物件是以 <a href="/zh-TW/DOM/The_structured_clone_algorithm">the structured clone algorithm</a> 序列化。這會允許更多種不同的物件可以被安全的傳送。</div> + +<h3 id="replaceState()_方法範例">replaceState() 方法範例</h3> + +<p>Suppose <span class="nowiki">http://mozilla.org/foo.html</span> executes the following JavaScript:</p> + +<pre class="brush: js">var stateObj = { foo: "bar" }; +history.pushState(stateObj, "page 2", "bar.html"); +</pre> + +<p>The explanation of these two lines above can be found at "Example of pushState() method" section. Then suppose <span class="nowiki">http://mozilla.org/bar.html</span> executes the following JavaScript:</p> + +<pre class="brush: js">history.replaceState(stateObj, "page 3", "bar2.html"); +</pre> + +<p>This will cause the URL bar to display <span class="nowiki">http://mozilla.org/bar2.html</span>, but won't cause the browser to load <code>bar2.html</code> or even check that <code>bar2.html</code> exists.</p> + +<p>Suppose now that the user now navigates to <span class="nowiki">http://www.microsoft.com</span>, then clicks back. At this point, the URL bar will display <span class="nowiki">http://mozilla.org/bar2.html. If the user now clicks back again, the URL bar will display http://mozilla.org/foo.html, and totaly bypass bar.html.</span></p> + +<h3 id="popstate_事件">popstate 事件</h3> + +<p>每次 active 的歷史紀錄被更動的時候，一個 <code>popstate</code> 事件會被發送到目前的 window。如果被啟用的歷史紀錄是由於呼叫 <code>pushState</code> 建立的或是呼叫 <code>replaceState</code> 所影響的，這個 <code>popstate</code> 事件的 <code>state</code> 屬性會含有一個歷史紀錄的 state object 的副本。</p> + +<p>使用範例參閱 {{ domxref("window.onpopstate") }}。</p> + +<h3 id="讀取目前的_state">讀取目前的 state</h3> + +<p>當你讀取頁面的時候，可能會有 non-null state 的物件。這會發生在，例如說，如果設定一個 state 物件（用 <code>pushState()</code> 或是 <code>replaceState()</code>），然後使用者重新啟動他的瀏覽器。當重新讀取你的頁面的時候，頁面會得到一個 <code>onload</code> 事件，但是沒有 <code>popstate</code> 事件。然而，如果你讀取了 <code> history.state</code> 屬性，你會得到像是 <code>popstate</code> 被觸發時，你會得到的 state object 。</p> + +<p>像這樣使用 <code>history.state</code> 屬性，你可以讀取目前的歷史紀錄的<code>狀態</code>而不需要等待一個 <code>popstate</code> 事件：</p> + +<pre class="brush: js">var currentState = history.state; +</pre> + +<h2 id="範例">範例</h2> + +<p>完整的 AJAX 網站範例 ，請參閱：<a href="/zh-TW/docs/DOM/Manipulating_the_browser_history/Example">Ajax navigation example</a>。</p> + +<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('HTML WHATWG', "browsers.html#history", "History")}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>No change from {{SpecName("HTML5 W3C")}}.</td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', "browsers.html#history", "History")}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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>replaceState, pushState</td> + <td>5</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{ CompatGeckoDesktop("2.0") }}</td> + <td>10</td> + <td>11.50</td> + <td>5.0</td> + </tr> + <tr> + <td>history.state</td> + <td>18</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{ CompatGeckoDesktop("2.0") }}</td> + <td>10</td> + <td>11.50</td> + <td>6.0</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>replaceState, pushState</td> + <td>{{ CompatUnknown() }}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + <tr> + <td>history.state</td> + <td>{{ CompatUnknown() }}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + </tbody> +</table> +</div> + +<p><strong style="font-size: 2.143rem; font-weight: 700; letter-spacing: -1px; line-height: 1;">參見</strong></p> + +<ul> + <li>{{ domxref("window.history") }}</li> + <li>{{ domxref("window.onpopstate") }}</li> +</ul> + +<p>{{ languages( { "ja": "ja/DOM/Manipulating_the_browser_history"} ) }}</p> diff --git a/files/zh-tw/web/api/html_drag_and_drop_api/drag_operations/index.html b/files/zh-tw/web/api/html_drag_and_drop_api/drag_operations/index.html new file mode 100644 index 0000000000..c609d6f4d4 --- /dev/null +++ b/files/zh-tw/web/api/html_drag_and_drop_api/drag_operations/index.html @@ -0,0 +1,336 @@ +--- +title: 拖曳操作 +slug: Web/API/HTML_Drag_and_Drop_API/Drag_operations +translation_of: Web/API/HTML_Drag_and_Drop_API/Drag_operations +--- +<p>{{DefaultAPISidebar("HTML Drag and Drop API")}}</p> + +<p>本文會一一說明拖曳各步驟的作業。</p> + +<p class="note">The drag operations described in this document use the {{domxref("DataTransfer")}} interface. This document does <em>not</em> use the {{domxref("DataTransferItem")}} interface nor the {{domxref("DataTransferItemList")}} interface.</p> + +<h2 id="draggableattribute" name="draggableattribute">Draggable 屬性</h2> + +<p>網頁中有些預設的拖曳行為，例如文字選擇、圖片或超連結，當拖曳圖片或超連結時，圖片或超連結的 URL 會被當作拖曳作業中所攜帶的資料，而其他類型元素則必須另外處理才能拖曳，試試看選擇網頁某一部分，然後按住滑鼠鍵來進行拖曳，依據OS不同，或許會有一些跟著滑鼠移動的效果，但這僅僅只是預設效果行為，實際上沒有任何資料跟著被拖曳。</p> + +<p>In HTML, apart from the default behavior for images, links, and selections, no other elements are draggable by default. In <a href="/en-US/docs/Mozilla/Tech/XUL">XUL</a>, all elements are draggable.</p> + +<p>除了文字選擇、圖片或超連結之外，沒有元素預設是可拖曳的。所以要讓一個元素可以拖曳，有幾件事必須要做：</p> + +<ul> + <li>在想要拖曳的元素上設定 <code>{{htmlattrxref("draggable")}}</code> 屬性為 <code>true</code>。</li> + <li>註冊 <code>{{event("dragstart")}}</code> 事件之事件處理器。</li> + <li>{{domxref("DataTransfer.setData","Set the drag data")}} within the listener defined above.</li> +</ul> + +<p>以下是一段簡單的範例。</p> + +<pre class="brush: html"><div draggable="true" ondragstart="event.dataTransfer.setData('text/plain', 'This text may be dragged')"> + This text <strong>may</strong> be dragged. +</div> +</pre> + +<p>draggable 為 true後，該 DIV 元素便可以拖曳，反之，倘若 draggable 為 false 或無設定則不可拖曳，只有其中下含的文字可以被選擇。draggable 屬性適用於任何元素，一般來說預設為false，除了圖片和連結預設為 true，所以說如果想要阻止圖片和連結被拖曳，則可以設定draggable 為 false。</p> + +<p>請注意，一旦元素被定為可拖曳之後，其下內含的文字或其他元素便無法像平常一樣用滑鼠選擇，使用者之能夠改用鍵盤或按住 Alt 鍵搭配滑鼠進行選擇。</p> + +<p>至於 XUL 元素則是預設皆可拖曳。</p> + +<pre class="brush: html"><button label="Drag Me" ondragstart="event.dataTransfer.setData('text/plain', 'Drag Me Button');"> +</pre> + +<h2 id="dragstart" name="dragstart">開始拖曳</h2> + +<p>下方範例在dragstart註冊一個事件處理器。</p> + +<pre class="brush: html"><div draggable="true" ondragstart="event.dataTransfer.setData('text/plain', 'This text may be dragged')"> + This text <strong>may</strong> be dragged. +</div> +</pre> + +<p>當拖曳作業開始，dragstart 事件會觸發，然後我們可以在事件處理器中準備好我們所要攜帶的資料、想要的拖曳回饋效果，不過基本上其實只需要準備資料就好，因為預設拖曳回饋效果已經足以應付大多數的狀況，此外，我們也可以改在上一層父元素註冊事件處理器，因為拖曳事件會上向傳遞 ( Bubble up ) 。</p> + +<h2 id="dragdata" name="dragdata">拖曳資料</h2> + +<p>所有的拖曳事件物件都有一個 <a href="/en-US/docs/DragDrop/DataTransfer" title="dataTransfer">dataTransfer</a> 屬性，這個屬性是用來攜帶資料。</p> + +<p>當拖曳時，資料必須和被拖曳目標作連結，比如說拖曳文字框中反白選擇的文字，那麼文字本身便是連結資料，同理，拖曳連結時URL便是連結資料。</p> + +<p>資料包含兩個部分，一是資料型態(或格式)、二是資料值。所謂資料型態是用文字描述資料型態(如<a href="/en-US/docs/DragDrop/Recommended_Drag_Types#text" style="line-height: 1.5;" title="text/plain">text/plain</a><span style="line-height: 1.5;">代表文字資料)，而資料值則是文字，要加入拖</span>曳<span style="line-height: 1.5;">資料需要提供資料的型態和內容值；有了資料後，我們可以在dragenter或dragover事件處理器中，透過檢查資料型態來決定是否可以接受後續的放置操作，比如說只接受連結類資料的拖</span>曳<span style="line-height: 1.5;">目標區(drop target)，會檢查資料型態是否為</span><a href="/en-US/docs/DragDrop/Recommended_Drag_Types#link" style="line-height: 1.5;" title="text/uri-list">text/uri-list</a><span style="line-height: 1.5;">。</span></p> + +<p>資料型態符合MIME型態，如<a href="/en-US/docs/DragDrop/Recommended_Drag_Types#text" style="line-height: 1.5;" title="text/plain">text/plain</a><span style="line-height: 1.5;">或</span><a href="/en-US/docs/DragDrop/Recommended_Drag_Types#image" style="line-height: 1.5;" title="image/jpeg">image/jpeg</a><span style="line-height: 1.5;">等等，而我們自己也可以自定義其他型態，最常使用的型態請見</span><a href="/en-US/docs/DragDrop/Recommended_Drag_Types" style="line-height: 1.5;" title="/en-US/docs/DragDrop/Recommended_Drag_Types">推薦拖曳資料型態</a>。</p> + +<p>一趟拖曳作業中可以攜帶多個多種型態的資料，所以我們可以自定義自己的型態同時，還提供其他資料給不認得自定義資料型態的其他拖曳目標區使用。通常最通用的資料會是文字類型資料。</p> + +<p>呼叫<a href="/en-US/docs/DragDrop/DataTransfer#setData.28.29" style="line-height: 1.5;" title="setData">setData</a><span style="line-height: 1.5;">方法，傳入資料型態和資料，這樣就可以攜帶想要的資料了：</span></p> + +<pre class="brush: js">event.dataTransfer.setData("text/plain", "Text to drag"); +</pre> + +<p>上例資料是”Text to drag”文字，型態是text/plain。</p> + +<p><span style="line-height: 1.5;">呼叫多次setData我們就可以攜帶多種資料。</span></p> + +<pre class="brush: js">var dt = event.dataTransfer; +dt.setData("application/x-bookmark", bookmarkString); +dt.setData("text/uri-list", "http://www.mozilla.org"); +dt.setData("text/plain", "http://www.mozilla.org"); +</pre> + +<p>這裡加入了三種資料，第一種是自定義的”application/x-bookmark”，雖然有更豐富的內容可使用，但只有我們自己認識，而另外我們又為其他網站或應用加入了兩種比較常見的資料，”text/uri-list”以及”text/plain”。</p> + +<p>如果對同一種資料型態加入兩次資料，則新加資料會取代舊資料。</p> + +<p><span style="line-height: 1.5;">呼叫</span><a href="/en-US/docs/DragDrop/DataTransfer#clearData.28.29" style="line-height: 1.5;" title="clearData">clearData</a><span style="line-height: 1.5;">會清除資料。</span></p> + +<pre class="brush: js">event.dataTransfer.clearData("text/uri-list"); +</pre> + +<p>如果呼叫clearData時有傳入資料型態，則只會清除該型態資料，如果沒有傳入任何型態，則所有資料皆會被清除。</p> + +<h2 id="dragfeedback" name="dragfeedback">設定拖曳圖片</h2> + +<p>當拖曳進行中，以拖曳元素為基礎，一個半透明的圖片會自動產生出來，並且跟著滑鼠移動。如果想要，我們也可以呼叫<code><a href="/en-US/docs/DragDrop/DataTransfer#setDragImage.28.29" title="setDragImage">setDragImage()來指定我們自己的拖曳使用圖片。</a></code></p> + +<pre class="brush: js">event.dataTransfer.setDragImage(image, xOffset, yOffset); +</pre> + +<p>setDragImage需要三個參數，一是圖片來源(通常是圖片元素，但也可以是canvas元素或其他元素)，拖曳使用圖片會依照圖片來源在螢幕上所顯示的樣子產生；二和三是圖片相對於滑鼠指標的位置位移量。</p> + +<p><span style="line-height: 1.5;">不過也是能夠使用文件外部的圖片或canvas元素，當需要透過canvas元素產生客製圖片時，這個技巧很有用，如下範例所示：</span></p> + +<pre class="brush: js">function dragWithCustomImage(event) { + var canvas = document.createElementNS("http://www.w3.org/1999/xhtml","canvas"); + canvas.width = canvas.height = 50; + + var ctx = canvas.getContext("2d"); + ctx.lineWidth = 4; + ctx.moveTo(0, 0); + ctx.lineTo(50, 50); + ctx.moveTo(0, 50); + ctx.lineTo(50, 0); + ctx.stroke(); + + var dt = event.dataTransfer; + dt.setData('text/plain', 'Data to Drag'); + dt.setDragImage(canvas, 25, 25); +} +</pre> + +<p>上面我們的canvas是50 x 50px大小，然後我們位移一半25讓圖片落在滑鼠指標中央。 </p> + +<p>{{h2_gecko_minversion("使用XUL panel元素作為拖曳圖片", "9.0")}}</p> + +<p>在Gecko上開發，比如說外掛或Mozllia應用程式，Gecko9.0{{geckoRelease("9.0")}}支援使用{{XULElem("panel")}}元素作為拖曳圖片，簡單將XUL panel元素傳入setDragImage方法即可。</p> + +<p>試想下面這個 {{XULElem("panel")}}元素:</p> + +<pre class="brush: xml"><<span class="start-tag">panel</span><span class="attribute-name"> id</span>=<span class="attribute-value">"panel" </span><span class="attribute-name">style</span>=<span class="attribute-value">"opacity: 0.6</span><span class="attribute-value">"</span>> + <<span class="start-tag">description</span><span class="attribute-name"> id</span>=<span class="attribute-value">"pb"</span>>Drag Me</<span class="end-tag">description</span>> +</<span class="end-tag">panel</span>> + +<<span class="start-tag">vbox</span><span class="attribute-name"> align</span>=<span class="attribute-value">"start" </span><span class="attribute-name">style</span>=<span class="attribute-value">"border: 1px solid black;" </span><span class="attribute-name">ondragstart</span>=<span class="attribute-value">"startDrag(event)"</span>> + <<span class="start-tag">description</span>>Drag Me</<span class="end-tag">description</span>> +</<span class="end-tag">vbox</span>> +</pre> + +<p>當使用者拖曳{{XULElem("vbox")}} 元素時，startDrag函數會被呼叫。</p> + +<pre class="brush: js"><span class="cdata">function startDrag(event) { + event.dataTransfer.setData("text/plain", "<strong>Body</strong>"); + event.dataTransfer.setDragImage(document.getElementById("panel"), 20, 20); +}</span> +</pre> + +<p>我們用HTML格式的"<strong>Body</strong>"作為資料，然後用pnael元素作為圖片。</p> + +<h2 id="drageffects" name="drageffects">拖曳效果</h2> + +<p>拖曳作業有好機種；copy作業代表被拖曳資料會被複製一份到拖曳目標區，move作業代表移動被拖曳的資料，link作業代表拖曳來源區和拖曳目標區有某種關係。</p> + +<p>在dragstart事件中可以設定<a href="/en-US/docs/DragDrop/DataTransfer#effectAllowed.28.29" style="line-height: 1.5;" title="effectAllowed">effectAllowed</a><span style="line-height: 1.5;">屬性，指定拖曳源頭允許的作業。</span></p> + +<pre class="brush: js">event.dataTransfer.effectAllowed = "copy"; +</pre> + +<p>上面只有copy被允許，但還有其他種類：</p> + +<p> 只能移動或連結。</p> + +<dl> + <dt>none</dt> + <dd>不允許任何作業。</dd> + <dt>copy</dt> + <dd>只能複製。</dd> + <dt>move</dt> + <dd>只能移動。</dd> + <dt>link</dt> + <dd>只有連結。</dd> + <dt>copyMove</dt> + <dd>只能複製或移動。</dd> + <dt>copyLink</dt> + <dd>只能複製或連結。</dd> + <dt>linkMove</dt> + <dt>all</dt> + <dd>複製、移動或連結皆可。</dd> +</dl> + +<p><a href="/en-US/docs/DragDrop/DataTransfer#effectAllowed.28.29" title="effectAllowed">effectAllowed</a> 屬性預設所有作業都接受，如all值。</p> + +<p>在dragenter或dragover事件中，我們可以藉由檢查effectAllowed來知道那些作業是被允許的，另外，另一個相關聯的<a href="/en-US/docs/DragDrop/DataTransfer#dropEffect.28.29" style="line-height: 1.5;" title="dropEffect">dropEffect</a><span style="line-height: 1.5;">屬性應該要是effectAllowed的其中一個作業，但是dropEffect不接受多重作業，只可以是none, copy, move和link。</span></p> + +<p>dropEffect屬性會在在dragenter以及dragover事件中初始化為使用者想要執行的作業效果，使用者能夠透過按鍵(依平台不同，通常是Shift或Ctrl鍵)，在複製、移動、連接作業之間切換，同時滑鼠指標也會跟著相應變換，例如複製作業的滑鼠旁會多出一個+的符號。</p> + +<p>effectAllowed和dropEffect屬性可以在dragenter或dragover事件中更改，更改effectAllowed屬性能讓拖曳作業只能在支援被允許作業類型的拖曳目標上執行，好比說effectAllowed為copyMove的作業就會阻止使用者進行link類型的作業。</p> + +<p>我們也可以更改dropEffect來強迫使用者執行某項作業，而且應該要是effectAllowed所列舉的作業。</p> + +<pre class="brush: js">event.dataTransfer.effectAllowed = "copyMove"; +event.dataTransfer.dropEffect = "copy"; +</pre> + +<p>上面的範例中copy就是會被執行的作業效果。</p> + +<p>若effectAllowed或dropEffect為none，那麼沒有放置作業可以被執行。</p> + +<h2 id="droptargets" name="droptargets">指定拖曳目標</h2> + +<p>dragenter和dragover事件就是用來指定拖曳目標區，也就是放置資料的目標區，絕大多數的元素預設的事件都不准放置資料。</p> + +<p>所以想要放置資料到元素上，就必須取消預設事件行為。取消預設事件行為能夠藉由回傳false或呼叫<a href="/en-US/docs/DOM/event.preventDefault" title="DOM/event.preventDefault">event.preventDefault</a>方法。</p> + +<pre class="brush: html"><div ondragover="return false"> +<div ondragover="event.preventDefault()"> +</pre> + +<p>通常我們只有在適當的時機點才需要呼叫event.preventDefault方法、取消預設事件行為，比如說被拖曳進來的是連結。所以檢查被拖曳進來的物件，當符合條件後再來取消預設事件行為。</p> + +<p>藉由檢查拖曳資料型態來決定是否允許放置，是最常見的作法。dataTransfer物件的<a href="/en-US/docs/DragDrop/DataTransfer#types.28.29" style="line-height: 1.5;" title="types">types</a><span style="line-height: 1.5;">屬性是一個拖曳資料型態的列表，其中順序按照資料被加入之先後排序。</span></p> + +<pre class="brush: js">function doDragOver(event) +{ + var isLink = event.dataTransfer.types.contains("text/uri-list"); + if (isLink) + event.preventDefault(); +} +</pre> + +<p>上面我們呼叫contains方法檢察text/uri-list是否存在拖曳資料型態的列表之內，有的話才取消預設行為、准許放置作業，否則，不取消預設行為、不准許放置作業。</p> + +<p>檢查拖曳資料型態後，我們也可以依此更動effectAllowed和dropEffect屬性，只不過，如果沒有取消預設行為，更動並不會有甚麼影響。</p> + +<h3 id="Updates_to_DataTransfer.types">Updates to DataTransfer.types</h3> + +<p>Note that the latest spec now dictates that {{domxref("DataTransfer.types")}} should return a frozen array of {{domxref("DOMString")}}s rather than a {{domxref("DOMStringList")}} (this is supported in Firefox 52 and above).</p> + +<p>As a result, the <a href="/en-US/docs/Web/API/Node/contains">contains</a> method no longer works on the property; the <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes">includes</a> method should be used instead to check if a specific type of data is provided, using code like the following:</p> + +<pre class="brush: js">if ([...event.dataTransfer.types].includes('text/html')) { + // Do something +}</pre> + +<p>You could always use some feature detection to determine which method is supported on <code>types</code>, and run code as appropriate.</p> + +<h2 id="dropfeedback" name="dropfeedback">放置回饋</h2> + +<p>有好幾種方法回饋使用者，告訴使用者甚麼元素可以接受放置作業，最簡單的是滑鼠會指標會自動變換樣式(視平台而定)。</p> + +<p>滑鼠指標提示雖然夠用了，不過有時我們還是會想做其他UI上的樣式變化。-moz-drag-over的CSS pseudo-class便可以應用在拖曳目標元素上。</p> + +<pre class="brush: css">.droparea:-moz-drag-over { + border: 1px solid black; +} +</pre> + +<p>當目標元素的dragenter預設事件有被取消時，這個pseudo-class就會啟動，目標UI會套用1px的黑色border，請注意dragover並不會檢查這項設定。</p> + +<p>其他比如說插入圖片等，在dragenter事件內執行更多更複雜的樣式變化也是可以的。</p> + +<p>倘若想要做出圖片更著滑鼠在拖曳目標區上面移動的效果，那麼可以在dragover事件內來取得的<a href="/en-US/docs/DOM/event.clientX" style="line-height: 1.5;" title="clientX">clientX</a><span style="line-height: 1.5;">和</span><a href="/en-US/docs/DOM/event.clientY" style="line-height: 1.5;" title="clientY">clientY</a><span style="line-height: 1.5;">的滑鼠座標資訊。</span></p> + +<p>最後，應該要在dragleave事件內復原之前所做樣式變更，dragleave事件不需要取消預設事件行為、永遠都會觸發，即使拖曳被取消了；至於使用-moz-drag-over的CSS方法的話，樣式復原會自動執行，不用擔心。</p> + +<h2 id="drop" name="drop">執行放置作業</h2> + +<p>當使用者在拖曳目標區上放開滑鼠時，drop事件就會觸發。<span style="line-height: 1.5;">當drop事件發生，我們需要取出被丟入的資料，然後處理之。</span></p> + +<p>要取出被丟入的資料，那就要呼叫dataTransfer物件的<a href="/en-US/docs/DragDrop/DataTransfer#getData.28.29" style="line-height: 1.5;" title="getData">getData</a><span style="line-height: 1.5;">方法。getData方法接受資料型態的參數，它會回傳</span><a href="/en-US/docs/DragDrop/DataTransfer#setData.28.29" style="line-height: 1.5;" title="setData">setData</a><span style="line-height: 1.5;">所存入的對應資料型態的資料，倘若沒有對應型態資料，那空字串就會被回傳。</span></p> + +<pre class="brush: js">function onDrop(event) +{ + var data = event.dataTransfer.getData("text/plain"); + event.target.textContent = data; + event.preventDefault(); +} </pre> + +<p><span style="line-height: 1.5;">上面的範例會取出文字資料，假設拖曳目標區是文字區域，例如p或div元素，那麼資料就會被當作文字內容，插入目標元素之中。</span></p> + +<p>網頁之中，如果我們已經處理過放置資料，那應該要呼叫{preventDefault}方法防止瀏覽器再次處理資料，比如說，Firefox預設是會開啟拖入的連結，但我們可以取消這項預設行為來避免開啟連結。</p> + +<p>當然也可以取得其他種類資料來使用，比如說連結資料，<a href="/en-US/docs/DragDrop/Recommended_Drag_Types#link" style="line-height: 1.5;" title="text/uri-list">text/uri-list</a><span style="line-height: 1.5;">。</span></p> + +<pre class="brush: js">function doDrop(event) +{ + var links = event.dataTransfer.getData("text/uri-list").split("\n"); + for each (var link in links) { + if (link.indexOf("#") == 0) + continue; + + var newlink = document.createElement("a"); + newlink.href = link; + newlink.textContent = link; + event.target.appendChild(newlink); + } + event.preventDefault(); +} +</pre> + +<p>上面的範例取得連結資料，然後生成連結元素、加入頁面。從text/uri-list字面上不難猜出這種資料是一行行的URL，所以我們呼叫<a href="/en-US/docs/JavaScript/Reference/Global_Objects/String/split" style="line-height: 1.5;" title="split">split</a><span style="line-height: 1.5;">方法拆開一行行的URL，再將URL一個一個加入頁面。請注意我們有避開開頭為”#”字元的註解。</span></p> + +<p>更簡單的作法是採用特別URL型態。URL型態是一個特殊簡寫用途形態，它不會出現在{types}屬性中，但它可以方便的取得第一個連結，如下:</p> + +<pre class="brush: js">var link = event.dataTransfer.getData("URL"); +</pre> + +<p>這個作法能夠省去檢查註解和一個一個掃過URL，但只會得到第一個URL。</p> + +<p>下面的例子會從多個支援的資料型態中，找出支援的資料。</p> + +<pre class="brush: js">function doDrop(event) +{ + var types = event.dataTransfer.types; + var supportedTypes = ["application/x-moz-file", "text/uri-list", "text/plain"]; + types = supportedTypes.filter(function (value) types.contains(value)); + if (types.length) + var data = event.dataTransfer.getData(types[0]); + event.preventDefault(); +}</pre> + +<h2 id="dragend" name="dragend">完成拖曳</h2> + +<p>拖曳作業完成後，不論成功或取消於否，被拖曳元素的<code style="line-height: 1.5;"><a href="/en-US/docs/Web/Reference/Events/dragend" style="line-height: 1.5;">dragend</a></code><span style="line-height: 1.5;">事件都會觸發，如果想要判別作業是否完成，可以檢查dropEffect屬性，若是dropEffect為none，代表拖曳作業被取消，否則dropEffect的值代表所完成的作業類型。</span></p> + +<p>有一個Gecko專屬的<a href="/en-US/docs/DragDrop/DataTransfer#mozUserCancelled.28.29" style="line-height: 1.5;" title="dropEffect">mozUserCancelled</a><span style="line-height: 1.5;">屬性，當使用者按ESC鍵取消拖曳後，這個屬性會為true，但若是因其他理由被取消或成功，則為false</span></p> + +<p>拖曳作業的放置可以發生在同一個視窗或其他應用程式，而且dragend事件還是會觸發，不過事件中的<a href="/en-US/docs/DOM/event.screenX" style="line-height: 1.5;" title="screenX">screenX</a><span style="line-height: 1.5;">與</span><a href="/en-US/docs/DOM/event.screenY" style="line-height: 1.5;" title="screenY">screenY</a><span style="line-height: 1.5;">屬性會是放置發生點的資訊。</span></p> + +<p>當dragend事件結束傳遞後，拖曳作業也完成了。</p> + +<p>[1] 在Gecko，如果被拖曳元素在拖曳作業還在進行中移動或刪除，那麼dragend事件就不會觸發。<a class="external" href="https://bugzilla.mozilla.org/show_bug.cgi?id=460801" title="New D&D API: dragend is not dispatched if the source node was moved or removed during the drag session">bug 460801</a></p> + +<div class="s3gt_translate_tooltip" id="s3gt_translate_tooltip" style="position: absolute; left: 107px; top: 546px; opacity: 0;"> +<div class="s3gt_translate_tooltip_mini" id="s3gt_translate_tooltip_mini_logo" title="翻譯選取的文字"> </div> + +<div class="s3gt_translate_tooltip_mini" id="s3gt_translate_tooltip_mini_sound" title="朗讀"> </div> + +<div class="s3gt_translate_tooltip_mini" id="s3gt_translate_tooltip_mini_copy" title="將文字複製到剪貼簿"> </div> +</div> + +<h2 id="See_also" name="See_also">參見</h2> + +<ul> + <li><a class="internal" href="/Web/API/HTML_Drag_and_Drop_API" title="HTML Drag and Drop API">HTML Drag and Drop API (Overview)</a></li> + <li><a class="internal" href="/Web/Guide/HTML/Dragging_and_Dropping_Multiple_Items" title="Dragging and Dropping Multiple Items">Dragging and Dropping Multiple Items</a></li> + <li><a class="internal" href="/Web/Guide/HTML/Recommended_Drag_Types" title="Recommended Drag Types">Recommended Drag Types</a></li> + <li><a href="https://html.spec.whatwg.org/multipage/interaction.html#dnd" title="Drag and Drop Standard">HTML5 Living Standard: Drag and Drop</a></li> +</ul> diff --git a/files/zh-tw/web/api/html_drag_and_drop_api/index.html b/files/zh-tw/web/api/html_drag_and_drop_api/index.html new file mode 100644 index 0000000000..ac7be3f0b0 --- /dev/null +++ b/files/zh-tw/web/api/html_drag_and_drop_api/index.html @@ -0,0 +1,249 @@ +--- +title: HTML 拖放 API +slug: Web/API/HTML_Drag_and_Drop_API +translation_of: Web/API/HTML_Drag_and_Drop_API +--- +<p>{{DefaultAPISidebar("HTML Drag and Drop API")}}</p> + +<p><span class="seoSummary">HTML 拖放介面能讓網頁應用程式於 Firefox 及其他瀏覽器中使用拖放功能。</span>舉例來說，使用者可以利用此功能以滑鼠選擇<em>可拖曳（draggable）</em>元素，拖曳至一個<em>可放置（droppable）</em>元素上，並放開滑鼠按鍵來放置此元素。在拖曳操作時，一個半透明的<em>可拖曳（draggable）</em>元素會跟隨著滑鼠游標。</p> + +<p>對於網站、擴充套件以及 XUL 應用程式來說，你可以自定義能成為<em>可拖曳（draggable）</em>的元素類型、<em>可拖曳（draggable）</em>元素產生的回鐀類型，以及<em>可放置（droppable）</em>的元素。</p> + +<p>此文件為 HTML 拖放的概述，包含了相關介面的說明、在應用程式中加入拖放支援的基本步驟，以及相關介面使用簡介。</p> + +<h2 id="events" name="events">拖曳事件</h2> + +<p>HTML 拖放操作基於 {{domxref("Event","DOM 事件模型")}}並且使用繼承自{{domxref("MouseEvent","滑鼠事件")}}的<em>{{domxref("DragEvent","拖曳事件")}}</em>介面。一個典型的拖曳操作開始於使用者利用滑鼠選取了一個<em>可拖曳（draggable）</em>元素、移動滑鼠至一個<em>可放置（droppable）</em>元素並放開滑鼠按鍵。在操作的過程中，會觸發多種類型的事件，且一些事件類型可能會被觸發多次（如 {{event("drag")}} 及 {{event("dragover")}} 事件類型）。</p> + +<p>所有的<a href="/zh-TW/docs/Web/API/DragEvent#Event_types">拖曳事件類型</a>都有相關的<a href="/zh-TW/docs/Web/API/DragEvent#GlobalEventHandlers">通用事件處理器</a>（global event handler）。每一種拖曳事件類型及拖曳通用事件處理器屬性都有說明此事件的參考文件。以下的表格提供了每一種事件的簡要說明，以及參考文件的連結。</p> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">事件</th> + <th scope="col">事件處理器屬性</th> + <th scope="col">說明</th> + </tr> + <tr> + <td>{{event('drag')}}</td> + <td>{{domxref('GlobalEventHandlers.ondrag','ondrag')}}</td> + <td>於一個元素或文字選取區塊被拖曳時觸發。</td> + </tr> + <tr> + <td>{{event('dragend')}}</td> + <td>{{domxref('GlobalEventHandlers.ondragend','ondragend')}}</td> + <td>於拖曳操作結束時觸發（如放開滑鼠按鍵或按下鍵盤的 escape 鍵）。（請參考<a href="/en-US/docs/DragDrop/Drag_Operations#dragend" title="Finishing a Drag">結束拖曳</a>。）</td> + </tr> + <tr> + <td>{{event('dragenter')}}</td> + <td>{{domxref('GlobalEventHandlers.ondragenter','ondragenter')}}</td> + <td>於一個元素或文字選取區塊被拖曳移動進入一個有效的放置目標時觸發。（請參考<a href="/en-US/docs/DragDrop/Drag_Operations#droptargets" title="Specifying Drop Targets">指定拖曳目標</a>。）</td> + </tr> + <tr> + <td>{{event('dragexit')}}</td> + <td>{{domxref('GlobalEventHandlers.ondragexit','ondragexit')}}</td> + <td>當一個元素不再是被選取中的拖曳元素時觸發。</td> + </tr> + <tr> + <td>{{event('dragleave')}}</td> + <td>{{domxref('GlobalEventHandlers.ondragleave','ondragleave')}}</td> + <td>於一個元素或文字選取區塊被拖曳移動離開一個有效的放置目標時觸發。</td> + </tr> + <tr> + <td>{{event('dragover')}}</td> + <td>{{domxref('GlobalEventHandlers.ondragover','ondragover')}}</td> + <td>於一個元素或文字選取區塊被拖曳移動經過一個有效的放置目標時觸發（每幾百毫秒觸發一次）。</td> + </tr> + <tr> + <td>{{event('dragstart')}}</td> + <td>{{domxref('GlobalEventHandlers.ondragstart','ondragstart')}}</td> + <td>於使用者開始拖曳一個元素或文字選取區塊時觸發。（請參考<a href="/en-US/docs/DragDrop/Drag_Operations#dragstart" title="Starting a Drag Operation">開始拖曳</a>。）</td> + </tr> + <tr> + <td>{{event('drop')}}</td> + <td>{{domxref('GlobalEventHandlers.ondrop','ondrop')}}</td> + <td>於一個元素或文字選取區塊被放置至一個有效的放置目標時觸發。（請參考<a href="/en-US/docs/DragDrop/Drag_Operations#drop" title="Performing a Drop">執行放置</a>。）</td> + </tr> + </tbody> +</table> + +<p class="note">注意：<code>dragstart</code> 與 <code>dragend</code> 事件，在把檔案從作業系統拖放到瀏覽器時，並不會觸發。</p> + +<h2 id="介面">介面</h2> + +<p>HTML 拖放介面有 {{domxref("DragEvent")}}、{{domxref("DataTransfer")}}、{{domxref("DataTransferItem")}} 以及 {{domxref("DataTransferItemList")}}。</p> + +<p>{{domxref("DragEvent")}} 介面擁有一個建構式及一個屬性－{{domxref("DragEvent.dataTransfer","dataTransfer")}} 屬性為一個 {{domxref("DataTransfer")}} 物件。{{domxref("DataTransfer")}} 物件包含了拖放事件的狀態，如正在進行的拖放事件類型（例如 <code>copy</code> 或 <code>move</code>）、拖放中的資料（一或多個項目）以及每一個<em>拖放項目（drag item）</em>的檔案類型（MIME type）。{{domxref("DataTransfer")}} 物件也擁有加入及移除拖放資料項目的方法。{{domxref("DragEvent")}} 與 {{domxref("DataTransfer")}} 介面應該是唯一須要加至應用程式中的 HTML 拖放功能。另外，請留意 Firefox 支援了一些 {{anch("Gecko specific interfaces","Gecko-specific 擴充")}}予 {{domxref("DataTransfer")}} 物件使用，雖然這些擴充只能在 Firefox 上作用。</p> + +<p>每個 {{domxref("DataTransfer")}} 物件都包含了 {{domxref("DataTransfer.items","items")}} 屬性。此屬性乃 {{domxref("DataTransferItem")}} 物件的 {{domxref("DataTransferItemList","list")}}。而每個 {{domxref("DataTransferItem")}} 物件，則代表著一個<em>拖放單元</em>，每個拖放單元則擁有代表該資料<em>種類</em>的 {{domxref("DataTransferItem.kind","kind")}} 屬性（<code>string</code> 或 <code>file</code>）、還有表示該單元檔案類型（如 MIME）的{{domxref("DataTransferItem.type","type")}} 屬性。另外，{{domxref("DataTransferItem")}} 物件能取得拖放單元的資料。</p> + +<p>{{domxref("DataTransferItemList")}} 物件為 {{domxref("DataTransferItem")}} 的列表。該物件列表擁有以下方法：給列表增加拖放單元、從列表刪除拖放單元、還有清除列表內所有的拖放單元。</p> + +<p>{{domxref("DataTransfer")}} 與 {{domxref("DataTransferItem")}} 介面的最大不同，就是前者使用同步的 {{domxref("DataTransfer.getData","getData()")}} 方法訪問拖放單元的資料；後者則使用非同步的 {{domxref("DataTransferItem.getAsString","getAsString()")}} 方法訪問。</p> + +<p class="note">注意：{{domxref("DragEvent")}} 與 {{domxref("DataTransfer")}} 介面受廣泛的桌面瀏覽器支援。但只有少數瀏覽器支援 {{domxref("DataTransferItem")}} 與 {{domxref("DataTransferItemList")}} 介面。請參見 {{anch("Interoperability")}} 以取得有關拖放功能互通性的資訊。</p> + +<h3 id="Gecko-specific_interfaces">Gecko-specific interfaces</h3> + +<p>Mozilla and Firefox support some features not in the standard drag and drop model. These are <em>convenience functions</em> to facilitate dragging multiple items and dragging non-string data (such as files). For more information, see <a href="/en-US/docs/DragDrop/Dragging_and_Dropping_Multiple_Items" title="Dragging and Dropping Multiple Items">Dragging and Dropping Multiple Items</a>. Additionally, see the {{domxref("DataTransfer")}} reference page for all of the <a href="/en-US/docs/Web/API/DataTransfer#Gecko_properties">Gecko-specific properties</a> and <a href="/en-US/docs/Web/API/DataTransfer#Gecko_methods">Gecko-specific methods</a>.</p> + +<h2 id="基本用法">基本用法</h2> + +<p>This section provides a summary of the basic steps to add drag and drop functionality to an application. Each section includes a description of the step, a short code example, and links to additional information.</p> + +<h3 id="Identify_what_is_draggable">Identify what is <em>draggable</em></h3> + +<p>To make an element <em>draggable</em> requires adding the {{htmlattrxref("draggable")}} attribute plus the {{domxref("GlobalEventHandlers.ondragstart","ondragstart")}} global event handler, as shown in the following code sample</p> + +<pre class="brush: js">function dragstart_handler(ev) { + console.log("dragStart"); + // Add the target element's id to the data transfer object + ev.dataTransfer.setData("text/plain", ev.target.id); +} + +<body> + <p id="p1" draggable="true" ondragstart="dragstart_handler(event);">This element is draggable.</p> +</body> +</pre> + +<p>See the <a href="/en-US/docs/Web/HTML/Global_attributes/draggable" title="draggable global attribute">draggable attribute reference</a> and the <a href="/en-US/docs/Web/Guide/HTML/Drag_operations#draggableattribute">Drag operations guide</a> for more information.</p> + +<h3 id="Define_the_drag's_data">Define the drag's data</h3> + +<p>The application is free to include any number of data items in a drag operation. Each data item is a {{domxref("DOMString","string")}} of a particular <code>type</code>, typically a MIME type such as <code>text/html</code>.</p> + +<p>Each {{domxref("DragEvent","drag event")}} has a {{domxref("DragEvent.dataTransfer","dataTransfer")}} property that <em>holds</em> the event's data. This property (which is a {{domxref("DataTransfer")}} object) also has methods to <em>manage</em> drag data. The {{domxref("DataTransfer.setData","setData()")}} method is used to add an item to the drag data, as shown in the following example.</p> + +<pre class="brush: js">function dragstart_handler(ev) { + // Add the drag data + ev.dataTransfer.setData("text/plain", ev.target.id); + ev.dataTransfer.setData("text/html", "<p>Example paragraph</p>"); + ev.dataTransfer.setData("text/uri-list", "http://developer.mozilla.org"); +} +</pre> + +<p>For a list of common data types used for drag and drop (such as text, HTML, links, and files), see <a href="/en-US/docs/DragDrop/Recommended_Drag_Types" title="Recommended Drag Types">Recommended Drag Types</a> and for more information about drag data, see <a href="/en-US/docs/Web/Guide/HTML/Drag_operations#dragdata" title="Drag Data">Drag Data</a>.</p> + +<h3 id="Define_the_drag_image">Define the drag image</h3> + +<p>By default, the browser supplies an image that appears beside the mouse pointer during a drag operation. However, an application may define a custom image by using the {{domxref("DataTransfer.setDragImage","setDragImage()")}} method as shown in the following example.</p> + +<pre class="brush: js">function dragstart_handler(ev) { + // Create an image and then use it for the drag image. + // NOTE: change "example.gif" to an existing image or the image + // will not be created and the default drag image will be used. + var img = new Image(); + img.src = 'example.gif'; + ev.dataTransfer.setDragImage(img, 10, 10); +} +</pre> + +<p>To learn more about drag feedback images, see <a href="/en-US/docs/DragDrop/Drag_Operations#dragfeedback" title="Setting the Drag Feedback Image">Setting the Drag Feedback Image</a>.</p> + +<h3 id="Define_the_drag_effect">Define the drag <em>effect</em></h3> + +<p>The {{domxref("DataTransfer.dropEffect","dropEffect")}} property is used to control the feedback (typically visual) the user is given during a drag and drop operation. It affects which cursor the browser displays while dragging. For example, when the user hovers over a target drop element, the browser's cursor may indicate the type of operation that will occur.</p> + +<p>Three effects may be defined:</p> + +<p><code>copy</code> indicates that the data being dragged will be copied from its present location to the drop location.</p> + +<p><code>move</code> indicates that the data being dragged will be moved</p> + +<p><code>link</code> indicates that some form of relationship or connection will be created between the source and drop locations.</p> + +<p>During the drag operation, the drag effects may be modified to indicate that certain effects are allowed at certain locations. If allowed, a drop may occur at that location.</p> + +<p>The following example shows how to use this property.</p> + +<pre class="brush: js">function dragstart_handler(ev) { + // Set the drag effect to copy + ev.dataTransfer.dropEffect = "copy"; +} +</pre> + +<p>See <a href="/en-US/docs/Web/Guide/HTML/Drag_operations#drageffects" title="Drag Effects">Drag Effects</a> for more details.</p> + +<h3 id="Define_a_drop_zone">Define a <em>drop zone</em></h3> + +<p>By default, the browser prevents anything from happening when dropping something onto the HTML element. To change that behavior so that an element becomes a <em>drop zone</em> or is <em>droppable</em>, the element must have both {{domxref("GlobalEventHandlers.ondragover","ondragover")}} and {{domxref("GlobalEventHandlers.ondrop","ondrop")}} event handler attributes. The following example shows how to use those attributes and includes basic event handlers for each attribute.</p> + +<pre class="brush: js">function dragover_handler(ev) { + ev.preventDefault(); + // Set the dropEffect to move + ev.dataTransfer.dropEffect = "move" +} +function drop_handler(ev) { + ev.preventDefault(); + // Get the id of the target and add the moved element to the target's DOM + var data = ev.dataTransfer.getData("text"); + ev.target.appendChild(document.getElementById(data)); +} +<body> + <div id="target" ondrop="drop_handler(event);" ondragover="dragover_handler(event);">Drop Zone</div> +</body> +</pre> + +<p>Note each handler calls {{domxref("Event.preventDefault","preventDefault()")}} to prevent additional event processing for this prevent (such as touch events or pointer events).</p> + +<p>For more information, see <a href="https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Drag_operations#droptargets">Specifying Drop Targets</a>.</p> + +<h3 id="Handle_the_drop_effect">Handle the drop <em>effect</em></h3> + +<p>The handler for the {{event("drop")}} event is free to process the drag data in an application specific way. Typically, an application will use the {{domxref("DataTransfer.getData","getData()")}} method to retrieve drag items and process them accordingly. Additionally, application semantics may differ depending on the value of the {{domxref("DataTransfer.dropEffect","dropEffect")}} and/or the state of modifier keys.</p> + +<p>The following example shows a drop handler getting the source element's id from the drag data and then using the id to move the source element to the drop element.</p> + +<pre class="brush: js">function dragstart_handler(ev) { + // Add the target element's id to the data transfer object + ev.dataTransfer.setData("text/plain", ev.target.id); + ev.dropEffect = "move"; +} +function dragover_handler(ev) { + ev.preventDefault(); + // Set the dropEffect to move + ev.dataTransfer.dropEffect = "move" +} +function drop_handler(ev) { + ev.preventDefault(); + // Get the id of the target and add the moved element to the target's DOM + var data = ev.dataTransfer.getData("text"); + ev.target.appendChild(document.getElementById(data)); +} +<body> + <p id="p1" draggable="true" ondragstart="dragstart_handler(event);">This element is draggable.</p> + <div id="target" ondrop="drop_handler(event);" ondragover="dragover_handler(event);">Drop Zone</div> +</body> +</pre> + +<p>For more information, see <a href="https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Drag_operations#drop">Performing a Drop</a>.</p> + +<h3 id="Drag_end">Drag end</h3> + +<p>At the end of a drag operation, the {{event("dragend")}} event fires at the <em>source</em> element - the element that was the target of the drag start. This event fires whether the drag completed or was canceled. The {{event("dragend")}} event handler can check the value of the {{domxref("DataTransfer.dropEffect","dropEffect")}} property to determine if the drag operation succeeded or not.</p> + +<p>For more information about handling the end of a drag operation, see <a href="/en-US/docs/DragDrop/Drag_Operations#dragend" title="Finishing a Drag">Finishing a Drag</a>.</p> + +<h2 id="Interoperability">Interoperability</h2> + +<p>As can be seen in the <a href="/en-US/docs/Web/API/DataTransferItem#Browser_compatibility">DataTransferItem interface's Browser Compatibility table</a>, drag-and-drop interoperability is relatively broad among desktop browsers (except the {{domxref("DataTransferItem")}} and {{domxref("DataTransferItemList")}} interfaces have less support). This data also indicates drag and drop support among mobile browsers is very low.</p> + +<h2 id="Examples_and_demos" name="Examples_and_demos">Examples and demos</h2> + +<ul> + <li><a href="https://mdn.github.io/dom-examples/drag-and-drop/copy-move-DataTransfer.html">Copying and moving elements with the <code>DataTransfer</code> interface</a></li> + <li><a href="http://mdn.github.io/dom-examples/drag-and-drop/copy-move-DataTransferItemList.html">Copying and moving elements with the <code>DataTransferListItem</code> interface</a></li> + <li>Dragging and dropping files; Firefox only: <a class="external" href="http://jsfiddle.net/9C2EF/" title="http://jsfiddle.net/9C2EF/">http://jsfiddle.net/9C2EF/</a></li> + <li>Dragging and dropping files; All browsers: <a class="external" href="https://jsbin.com/hiqasek/edit?html,js,output" title="https://jsbin.com/hiqasek">https://jsbin.com/hiqasek/</a></li> + <li>A parking project using the Drag and Drop API: <a href="https://park.glitch.me/">https://park.glitch.me/</a> (You can edit <a href="https://glitch.com/edit/#!/park">here</a>)</li> +</ul> + +<h2 id="See_also" name="See_also">參見</h2> + +<ul> + <li><a class="internal" href="/en-US/docs/Web/API/HTML_Drag_and_Drop_API/Drag_operations" title="Drag Operations">Drag Operations</a></li> + <li><a class="internal" href="/en-US/docs/Web/API/HTML_Drag_and_Drop_API/Multiple_items" title="Dragging and Dropping Multiple Items">Dragging and Dropping Multiple Items</a></li> + <li><a class="internal" href="/en-US/docs/Web/API/HTML_Drag_and_Drop_API/Recommended_drag_types" title="Recommended Drag Types">Recommended Drag Types</a></li> + <li><a href="https://html.spec.whatwg.org/multipage/interaction.html#dnd" title="Drag and Drop Standard">HTML5 Living Standard: Drag and Drop</a></li> + <li><a href="http://caniuse.com/#search=draganddrop" title="Drag and Drop interoperability data from CanIUse">Drag and Drop interoperability data from CanIUse</a></li> +</ul> diff --git a/files/zh-tw/web/api/htmlcanvaselement/index.html b/files/zh-tw/web/api/htmlcanvaselement/index.html new file mode 100644 index 0000000000..fffa314976 --- /dev/null +++ b/files/zh-tw/web/api/htmlcanvaselement/index.html @@ -0,0 +1,262 @@ +--- +title: HTMLCanvasElement +slug: Web/API/HTMLCanvasElement +tags: + - API + - Canvas + - HTML DOM + - Interface + - NeedsTranslation + - Reference + - TopicStub +translation_of: Web/API/HTMLCanvasElement +--- +<div> +<div>{{APIRef("Canvas API")}}</div> +</div> + +<p><strong><code><span>HTMLCanvasElement</span></code></strong> 介面提供控制 canvas 元素的屬性和方法. <code>HTMLCanvasElement</code> 介面也繼承了 {{domxref("HTMLElement")}} 介面的屬性和方法.</p> + +<p>{{InheritanceDiagram}}</p> + +<h2 id="屬性">屬性</h2> + +<p><em>從父代繼承的屬性，</em><em>{{domxref("HTMLElement")}}.</em></p> + +<dl> + <dt>{{domxref("HTMLCanvasElement.height")}}</dt> + <dd>Is a positive <code>integer</code> reflecting the {{htmlattrxref("height", "canvas")}} HTML attribute of the {{HTMLElement("canvas")}} element interpreted in CSS pixels. When the attribute is not specified, or if it is set to an invalid value, like a negative, the default value of <code>150</code> is used.</dd> + <dt>{{domxref("HTMLCanvasElement.mozOpaque")}} {{non-standard_inline}}</dt> + <dd>Is a {{jsxref("Boolean")}} reflecting the {{htmlattrxref("moz-opaque", "canvas")}} HTML attribute of the {{HTMLElement("canvas")}} element. It lets the canvas know whether or not translucency will be a factor. If the canvas knows there's no translucency, painting performance can be optimized.</dd> + <dt>{{domxref("HTMLCanvasElement.width")}}</dt> + <dd>Is a positive <code>integer</code> reflecting the {{htmlattrxref("width", "canvas")}} HTML attribute of the {{HTMLElement("canvas")}} element interpreted in CSS pixels. When the attribute is not specified, or if it is set to an invalid value, like a negative, the default value of <code>300</code> is used.</dd> + <dt>{{domxref("HTMLCanvasElement.mozPrintCallback")}}{{non-standard_inline}}</dt> + <dd>Is a <code>function</code> that is Initially null, Web content can set this to a JavaScript function that will be called if the page is printed. This function can then redraw the canvas at a higher resolution that is suitable for the printer being used. <a href="https://blog.mozilla.org/labs/2012/09/a-new-way-to-control-printing-output/">See this blog post.</a></dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>從父代繼承的方法, </em><em>{{domxref("HTMLElement")}}.</em></p> + +<dl> + <dt>{{domxref("HTMLCanvasElement.captureStream()")}} {{experimental_inline}}</dt> + <dd>Returns a {{domxref("CanvasCaptureMediaStream")}} that is a real-time video capture of the surface of the canvas.</dd> + <dt>{{domxref("HTMLCanvasElement.getContext()")}}</dt> + <dd>Returns a drawing context on the canvas, or null if the context ID is not supported. A drawing context lets you draw on the canvas. Calling getContext with <code>"2d"</code> returns a {{domxref("CanvasRenderingContext2D")}} object, whereas calling it with <code>"experimental-webgl"</code> (or <code>"webgl"</code>) returns a {{domxref("WebGLRenderingContext")}} object. This context is only available on browsers that implement <a href="/en-US/docs/Web/WebGL">WebGL</a>.</dd> + <dt>{{domxref("HTMLCanvasElement.toDataURL()")}}</dt> + <dd>Returns a data-URL containing a representation of the image in the format specified by the <code>type</code> parameter (defaults to <code>png</code>). The returned image is in a resolution of 96dpi.</dd> + <dt>{{domxref("HTMLCanvasElement.toBlob()")}}</dt> + <dd>Creates a {{domxref("Blob")}} object representing the image contained in the canvas; this file may be cached on the disk or stored in memory at the discretion of the user agent.</dd> + <dt>{{domxref("HTMLCanvasElement.mozGetAsFile()")}} {{non-standard_inline}} {{deprecated_inline}}</dt> + <dd>Returns a {{domxref("File")}} object representing the image contained in the canvas; this file is a memory-based file, with the specified <code>name</code>. If <code>type</code> is not specified, the image type is <code>image/png</code>.</dd> +</dl> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">註</th> + </tr> + <tr> + <td>{{SpecName('Media Capture DOM Elements', '#html-media-element-media-capture-extensions', 'HTMLCanvasElement')}}</td> + <td>{{Spec2('Media Capture DOM Elements')}}</td> + <td>Adds the method <code>captureStream()</code>.</td> + </tr> + <tr> + <td>{{SpecName('HTML WHATWG', "#the-canvas-element", "HTMLCanvasElement")}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>The method <code>getContext()</code> now returns a {{domxref("RenderingContext")}} rather than an opaque <code>object</code>.<br> + The methods <code>probablySupportsContext()</code>, <code>setContext()</code> and <code>transferControlToProxy()</code>have been added.</td> + </tr> + <tr> + <td>{{SpecName('HTML5.1', "scripting-1.html#the-canvas-element", "HTMLCanvasElement")}}</td> + <td>{{Spec2('HTML5.1')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', "scripting-1.html#the-canvas-element", "HTMLCanvasElement")}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>Initial definition.</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 (<code>2D</code> context)</td> + <td>4.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop('1.9.2')}}</td> + <td>9.0</td> + <td>9.0 [1]</td> + <td>3.1</td> + </tr> + <tr> + <td><code>toBlob()</code></td> + <td>50</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop('19')}} [2]</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}} (bug <a href="https://bugs.webkit.org/show_bug.cgi?id=71270">71270</a>)</td> + </tr> + <tr> + <td><code>probablySupportsContext()</code>,<br> + <code>setContext()</code>,<br> + <code>transferControlToProxy()</code> {{experimental_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>mozGetAsFile()</code> {{non-standard_inline}} {{deprecated_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop('2')}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>captureStream()</code> {{experimental_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop('41')}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>transferControlToOffscreen()</code> {{experimental_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop(44)}} [3]</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</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>Chrome for Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support (<code>2D</code> context)</td> + <td>2.1</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>10.0 [1]</td> + <td>3.2</td> + </tr> + <tr> + <td><code>webgl</code> context</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}} as <code>experimental-webgl</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>toBlob()</code></td> + <td>{{CompatNo}} (bug <a href="http://crbug.com/67587">67587</a>)</td> + <td>50</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile('18')}} [2]</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}} (bug <a href="https://bugs.webkit.org/show_bug.cgi?id=71270">71270</a>)</td> + </tr> + <tr> + <td><code>probablySupportsContext()</code>,<br> + <code>setContext()</code>,<br> + <code>transferControlToProxy() </code>{{experimental_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>mozGetAsFile()</code> {{non-standard_inline}} {{deprecated_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile('2')}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>captureStream() </code>{{experimental_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile('41')}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>transferControlToOffscreen()</code> {{experimental_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile(44)}} [3]</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Opera Mini 5.0 and later has partial support.</p> + +<p>[2] Support for the third parameter, has been added in Gecko 25 only: when used with the <code>"image/jpeg"</code> type, this argument specifies the image quality.</p> + +<p>[3] This feature is behind a feature preference setting. In about:config, set <code>gfx.offscreencanvas.enabled</code> to <code>true</code>.</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li>HTML element implementing this interface: {{HTMLElement("canvas")}}.</li> +</ul> diff --git a/files/zh-tw/web/api/htmlcanvaselement/todataurl/index.html b/files/zh-tw/web/api/htmlcanvaselement/todataurl/index.html new file mode 100644 index 0000000000..7a87309580 --- /dev/null +++ b/files/zh-tw/web/api/htmlcanvaselement/todataurl/index.html @@ -0,0 +1,201 @@ +--- +title: HTMLCanvasElement.toDataURL() +slug: Web/API/HTMLCanvasElement/toDataURL +tags: + - API + - Canvas +translation_of: Web/API/HTMLCanvasElement/toDataURL +--- +<div> +<div> +<div>{{APIRef("Canvas API")}}</div> +</div> +</div> + +<p><strong><code>HTMLCanvasElement.toDataURL()</code></strong> 方法回傳含有圖像和參數設置特定格式的 <a href="/en-US/docs/Web/HTTP/data_URIs">data URIs</a> (預設 <a href="https://en.wikipedia.org/wiki/Portable_Network_Graphics">PNG</a>). 回傳的圖像解析度為 96 dpi.</p> + +<ul> + <li>如果 canvas 的高度或是寬度為 <code>0</code>, 將會回傳字串 <code>"data:,"</code>.</li> + <li>如果要求的圖像類型並非 <code>image/png</code>, 但是回傳的類型卻是 <code>data:image/png</code>, 表示要求的圖像類型並不支援.</li> + <li>Chrome 也支援 <code>image/webp</code> 類型.</li> +</ul> + +<h2 id="Syntax" name="Syntax">表達式</h2> + +<pre class="syntaxbox"><var><em>canvas</em>.toDataURL(<em>type</em>, <em>encoderOptions</em>);</var> +</pre> + +<h3 id="參數">參數</h3> + +<dl> + <dt><code>type</code> {{optional_inline}}</dt> + <dd>圖像格式的 {{domxref("DOMString")}}. 預設為 <code>image/png</code>.</dd> + <dt><code>encoderOptions</code> {{optional_inline}}</dt> + <dd><code>表示 image/jpeg 或是 image/webp 的圖像品質, 為0</code> 到 <code>1</code> 之間的 {{jsxref("Number")}}.<br> + 如果值不在上述範圍中, 將會使用預設值. 其他的會忽略.</dd> +</dl> + +<h3 id="回傳值">回傳值</h3> + +<p>包含 <a href="/en-US/docs/Web/HTTP/data_URIs">data URI</a> 的 {{domxref("DOMString")}}.</p> + +<h2 id="範例">範例</h2> + +<p>創建 {{HTMLElement("canvas")}} 元素:</p> + +<pre class="brush: html"><canvas id="canvas" width="5" height="5"></canvas> +</pre> + +<p>可以使用下面的方式獲取 data-URL:</p> + +<pre class="brush: js">var canvas = document.getElementById("canvas"); +var dataURL = canvas.toDataURL(); +console.log(dataURL); +// "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNby +// blAAAADElEQVQImWNgoBMAAABpAAFEI8ARAAAAAElFTkSuQmCC" +</pre> + +<h3 id="設置圖像的品質">設置圖像的品質</h3> + +<pre class="brush: js">var fullQuality = canvas.toDataURL("image/jpeg", 1.0); +// data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...9oADAMBAAIRAxEAPwD/AD/6AP/Z" +var mediumQuality = canvas.toDataURL("image/jpeg", 0.5); +var lowQuality = canvas.toDataURL("image/jpeg", 0.1); +</pre> + +<h3 id="Example:_Dynamically_change_images" name="Example:_Dynamically_change_images">範例: 動態改變圖像</h3> + +<p>為了動態改變圖像, 可以與滑鼠事件一起使用 (gray-scale versus color in this example):</p> + +<h4 id="HTML">HTML</h4> + +<pre class="brush: html"><img class="grayscale" src="myPicture.png" alt="Description of my picture" /></pre> + +<h4 id="JavaScript">JavaScript</h4> + +<pre class="brush: js;highlight:[33]">window.addEventListener("load", removeColors); + +function showColorImg() { + this.style.display = "none"; + this.nextSibling.style.display = "inline"; +} + +function showGrayImg() { + this.previousSibling.style.display = "inline"; + this.style.display = "none"; +} + +function removeColors() { + var aImages = document.getElementsByClassName("grayscale"), + nImgsLen = aImages.length, + oCanvas = document.createElement("canvas"), + oCtx = oCanvas.getContext("2d"); + for (var nWidth, nHeight, oImgData, oGrayImg, nPixel, aPix, nPixLen, nImgId = 0; nImgId < nImgsLen; nImgId++) { + oColorImg = aImages[nImgId]; + nWidth = oColorImg.offsetWidth; + nHeight = oColorImg.offsetHeight; + oCanvas.width = nWidth; + oCanvas.height = nHeight; + oCtx.drawImage(oColorImg, 0, 0); + oImgData = oCtx.getImageData(0, 0, nWidth, nHeight); + aPix = oImgData.data; + nPixLen = aPix.length; + for (nPixel = 0; nPixel < nPixLen; nPixel += 4) { + aPix[nPixel + 2] = aPix[nPixel + 1] = aPix[nPixel] = (aPix[nPixel] + aPix[nPixel + 1] + aPix[nPixel + 2]) / 3; + } + oCtx.putImageData(oImgData, 0, 0); + oGrayImg = new Image(); + oGrayImg.src = oCanvas.toDataURL(); + oGrayImg.onmouseover = showColorImg; + oColorImg.onmouseout = showGrayImg; + oCtx.clearRect(0, 0, nWidth, nHeight); + oColorImg.style.display = "none"; + oColorImg.parentNode.insertBefore(oGrayImg, oColorImg); + } +}</pre> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">註</th> + </tr> + <tr> + <td>{{SpecName('HTML WHATWG', "scripting.html#dom-canvas-todataurl", "HTMLCanvasElement.toDataURL")}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>No change since the latest snapshot, {{SpecName('HTML5 W3C')}}</td> + </tr> + <tr> + <td>{{SpecName('HTML5.1', "scripting-1.html#dom-canvas-todataurl", "HTMLCanvasElement.toDataURL")}}</td> + <td>{{Spec2('HTML5.1')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', "scripting-1.html#dom-canvas-todataurl", "HTMLCanvasElement.toDataURL")}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>Snapshot of the {{SpecName('HTML WHATWG')}} containing the initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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(4) }}</td> + <td>{{ CompatGeckoDesktop("1.9.2") }}</td> + <td>{{ CompatIE(9) }}</td> + <td>{{ CompatOpera(9) }}</td> + <td>{{ CompatSafari(4.0) }}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{ CompatAndroid(3.2) }}</td> + <td>{{ CompatAndroid(18) }}</td> + <td>{{ CompatGeckoMobile("1.9.2") }}</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatOpera(19) }}</td> + <td><span style="font-size: 12px; line-height: 18px;">{{ CompatSafari(3.0) }}</span></td> + </tr> + </tbody> +</table> +</div> + +<h2 id="See_Also" name="See_Also">參見</h2> + +<ul> + <li>The interface defining it, {{domxref("HTMLCanvasElement")}}.</li> + <li><a href="/en-US/docs/Web/HTTP/data_URIs">Data URIs</a> in the <a href="/en-US/docs/Web/HTTP">HTTP</a> reference.</li> +</ul> diff --git a/files/zh-tw/web/api/htmlcollection/index.html b/files/zh-tw/web/api/htmlcollection/index.html new file mode 100644 index 0000000000..dac516a65b --- /dev/null +++ b/files/zh-tw/web/api/htmlcollection/index.html @@ -0,0 +1,95 @@ +--- +title: HTMLCollection +slug: Web/API/HTMLCollection +translation_of: Web/API/HTMLCollection +--- +<p>{{APIRef("HTML DOM")}}</p> + +<p><strong><code>HTMLCollection</code></strong> 介面表示了一種成員為 {{domxref("Element")}} 物件的通用集合（如 <a href="/zh-TW/docs/Web/JavaScript/Reference/Functions/arguments">arguments</a> 一般的類陣列，成員順序同元素在文件中的順序），並提供了可用來選取集合成員的方法與屬性。</p> + +<div class="note"><strong>Note:</strong> This interface is called <code>HTMLCollection</code> for historical reasons (before DOM4, collections implementing this interface could only have HTML elements as their items).</div> + +<p><code>HTMLCollection</code> 物件對 HTML DOM 而言具有即時性（live），如果底層的文件（<code>document</code> 物件）發生改變，<code>HTMLCollection</code> 物件會自動更新至最新的狀態。</p> + +<h2 id="屬性">屬性</h2> + +<dl> + <dt>{{domxref("HTMLCollection.length")}} {{readonlyInline}}</dt> + <dd>Returns the number of items in the collection.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<dl> + <dt>{{domxref("HTMLCollection.item()")}}</dt> + <dd>Returns the specific node at the given zero-based <code>index</code> into the list. Returns <code>null</code> if the <code>index</code> is out of range.</dd> + <dt>{{domxref("HTMLCollection.namedItem()")}}</dt> + <dd>Returns the specific node whose ID or, as a fallback, name matches the string specified by <code>name</code>. Matching by name is only done as a last resort, only in HTML, and only if the referenced element supports the <code>name</code> attribute. Returns <code>null</code> if no node exists by the given name.</dd> +</dl> + +<h2 id="Usage_in_JavaScript">Usage in JavaScript</h2> + +<p><code>HTMLCollection also</code> exposes its members directly as properties by both name and index. HTML IDs may contain : and . as valid characters, which would necessitate using bracket notation for property access. Currently HTMLCollections does not recognize purely numeric IDs, which would cause conflict with the array-style access, though HTML5 does permit these.</p> + +<p>For example, assuming there is one <code><form></code> element in the document and its <code>id</code> is <code>"myForm"</code>:</p> + +<pre class="brush:js">var elem1, elem2; + +// document.forms is an HTMLCollection + +elem1 = document.forms[0]; +elem2 = document.forms.item(0); + +alert(elem1 === elem2); // shows: "true" + +elem1 = document.forms.myForm; +elem2 = document.forms.namedItem("myForm"); + +alert(elem1 === elem2); // shows: "true" + +elem1 = document.forms["named.item.with.periods"];</pre> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>Different browsers behave differently when there are more than one elements matching the string used as an index (or <code>namedItem</code>'s argument). Firefox 8 behaves as specified in DOM 2 and DOM4, returning the first matching element. WebKit browsers and Internet Explorer in this case return another <code>HTMLCollection</code> and Opera returns a {{domxref("NodeList")}} of all matching elements.</p> + +<h2 id="Specifications" name="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('DOM WHATWG', '#htmlcollection', 'HTMLCollection')}}</td> + <td>{{ Spec2('DOM WHATWG') }}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM4', '#htmlcollection', 'HTMLCollection')}}</td> + <td>{{ Spec2('DOM4') }}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM2 HTML', 'html.html#ID-75708506', 'HTMLCollection')}}</td> + <td>{{ Spec2('DOM2 HTML') }}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM1', 'level-one-html.html#ID-75708506', 'HTMLCollection')}}</td> + <td>{{ Spec2('DOM1') }}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("NodeList")}}</li> + <li>{{domxref("HTMLFormControlsCollection")}}, {{domxref("HTMLOptionsCollection")}}</li> +</ul> diff --git a/files/zh-tw/web/api/htmldataelement/index.html b/files/zh-tw/web/api/htmldataelement/index.html new file mode 100644 index 0000000000..56e15b834d --- /dev/null +++ b/files/zh-tw/web/api/htmldataelement/index.html @@ -0,0 +1,59 @@ +--- +title: HTMLDataElement +slug: Web/API/HTMLDataElement +translation_of: Web/API/HTMLDataElement +--- +<div>{{APIRef("HTML DOM")}}</div> + +<p>The <strong><code>HTMLDataElement</code></strong> interface provides special properties (beyond the regular {{domxref("HTMLElement")}} interface it also has available to it by inheritance) for manipulating {{HTMLElement("data")}} elements.</p> + +<p>{{InheritanceDiagram(600, 120)}}</p> + +<h2 id="屬性">屬性</h2> + +<p><em>從它的父繼承屬性, {{domxref("HTMLElement")}}.</em></p> + +<dl> + <dt>{{domxref("HTMLDataElement.value")}}</dt> + <dd>Is a {{domxref("DOMString")}} reflecting the {{htmlattrxref("value", "data")}} HTML attribute, containing a machine-readable form of the element's value.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>無具體的方法; 從它的父繼承, {{domxref("HTMLElement")}}.</em></p> + +<h2 id="Specifications">Specifications</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('HTML WHATWG', "#htmldataelement", "HTMLDataElement")}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', 'text-level-semantics.html#the-data-element', 'HTMLDataElement')}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<div> + + +<p>{{Compat("api.HTMLDataElement")}}</p> +</div> + +<h2 id="See_also">See also</h2> + +<ul> + <li>The HTML element implementing this interface: {{HTMLElement("data")}}.</li> +</ul> diff --git a/files/zh-tw/web/api/htmldocument/index.html b/files/zh-tw/web/api/htmldocument/index.html new file mode 100644 index 0000000000..7317d54508 --- /dev/null +++ b/files/zh-tw/web/api/htmldocument/index.html @@ -0,0 +1,16 @@ +--- +title: HTMLDocument +slug: Web/API/HTMLDocument +translation_of: Web/API/HTMLDocument +--- +<p>{{ APIRef("HTML DOM") }}</p> + +<p><strong><code>HTMLDocument</code></strong> 是一個關於 {{domxref("Document_Object_Model", "DOM")}} 的抽象介面，提供了 {{domxref("Document")}} 定義之外的 XML 文件屬性及方法，以用來操作 HTML。</p> + +<p><code>window.document</code> 為 <code>HTMLDocument</code> 的物件實體，<code>HTMLDocument</code> 所有屬性與方法的說明已包含在 <code>Document</code> 頁面。由於現在的 <code>HTMLDocument</code> 是透過了綁定轉型（binding-specific casting）的方式來運作，所以 <code>HTMLDocument</code> 已不再是繼承 <code>Document</code>。</p> + +<h2 id="規範">規範</h2> + +<ul> + <li><a class="external" href="http://www.w3.org/TR/DOM-Level-2-HTML/html.html#ID-26809268" rel="freelink">http://www.w3.org/TR/DOM-Level-2-HTM...ml#ID-26809268</a></li> +</ul> diff --git a/files/zh-tw/web/api/htmlelement/click/index.html b/files/zh-tw/web/api/htmlelement/click/index.html new file mode 100644 index 0000000000..123206ca2f --- /dev/null +++ b/files/zh-tw/web/api/htmlelement/click/index.html @@ -0,0 +1,115 @@ +--- +title: HTMLElement.click() +slug: Web/API/HTMLElement/click +translation_of: Web/API/HTMLElement/click +--- +<div> +<div>{{ APIRef("HTML DOM") }}</div> +</div> + +<p><code><strong>HTMLElement.click()</strong></code> 方法可以模擬滑鼠點擊一個元素。</p> + +<p>當 <code>click()</code> 被使用在支援的元素（例如任一 {{HTMLElement("input")}} 元素），便會觸發該元素的點擊事件。事件會冒泡至 document tree（或 event chain）的上層元素，並觸發它們的點擊事件。其中的例外是：<code>click()</code> 方法不會讓 {{HTMLElement("a")}} 元素和接收到真實滑鼠點擊一樣進行頁面跳轉。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><em>elt</em>.click()</pre> + +<h2 id="規範">規範</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('DOM2 HTML', 'html.html#ID-2651361')}}</td> + <td>{{Spec2('DOM2 HTML')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>20<sup>[3]</sup></td> + <td>{{CompatVersionUnknown}}</td> + <td>5<sup>[1]</sup></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}<sup>[2]</sup></td> + <td>6<sup>[3]</sup></td> + </tr> + <tr> + <td><code>input@file (limited)</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>4</td> + <td>{{CompatVersionUnknown}}</td> + <td>12.10</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>input@file (full)</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>4</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Prior to Gecko 5.0 {{geckoRelease("5.0")}}, Gecko would not implement the <code>click()</code> method on other elements that might be expected to respond to mouse clicks, such as links ({{HTMLElement("a")}} elements), nor would it necessarily fire the click event of other elements.</p> + +<p>[2] In Presto-based versions of Opera, the <code>click()</code> method will be silently ignored if made on an {{HTMLElement("input")}} with its <strong><code>type</code> </strong>attribute set to <code>file</code> and its <a href="/en-US/docs/Web/CSS">CSS</a> {{cssxref('display')}} property set to <code>none</code>.</p> + +<p>[3] Older versions had <code>HTMLInputElement.click()</code>, and <code>HTMLButtonElement.click()</code> only.</p> diff --git a/files/zh-tw/web/api/htmlelement/dataset/index.html b/files/zh-tw/web/api/htmlelement/dataset/index.html new file mode 100644 index 0000000000..690f8e1189 --- /dev/null +++ b/files/zh-tw/web/api/htmlelement/dataset/index.html @@ -0,0 +1,167 @@ +--- +title: HTMLElement.dataset +slug: Web/API/HTMLElement/dataset +translation_of: Web/API/HTMLOrForeignElement/dataset +--- +<p>{{ APIRef("HTML DOM") }}</p> + +<p><code><strong>HTMLElement.dataset</strong></code> 允許在讀取與寫入模式時使用HTML或DOM裡，所有設置在元件上的<a href="/en/HTML/Global_attributes#attr-data-*" title="https://developer.mozilla.org/en/HTML/Global_attributes#attr-data-*">自定義資料屬性</a>(<em>data-*</em>)。他是一個<a href="/en/DOM/DOMStringMap" title="en/DOM/DOMStringMap">DOMStringMap</a>,每個項目表示一個不同的資料屬性。須注意的是，資料集(dataset)可以被讀取，但不能直接被修改。所有修改必須經由其眾多"屬性"才行，也就是資料屬性。另外，雖然HTML <code><strong>data-</strong></code> 屬性與它相關的 DOM <code><strong>dataset.</strong></code> 名稱不同，但是他們總是有相似之處： </p> + +<ul> + <li>HTML裡的自定義資料屬性名稱開頭為<code>data-</code> 。後面則只接受字母、數字還有以下的符號: dash (<code>-</code>), 點 (<code>.</code>), 冒號 (<code>:</code>), 底線(<code>_</code>) -- 但不包含任何ASCII 大寫字母(A 到 Z)。</li> + <li>Javascript 裡的自定義資料屬性和HTML裡的一樣，只是命名規則採camelCase，且不含dash,點等上述所提的符號。</li> +</ul> + +<p>除了以下的資訊之外，你也可以在 <a href="/en-US/docs/Learn/HTML/Howto/Use_data_attributes">Using data attributes.</a>此篇文章找到使用HTML資料屬性的用法。</p> + +<h3 id="名稱變換">名稱變換</h3> + +<p> </p> + +<p>dash-style 到 camelCase: 將自訂義的資料屬性名稱變換至{{ domxref("DOMStringMap") }}各項目的key值，需根據以下規則：</p> + +<ul> + <li>移除前綴<code>data-</code>(包含dash)。</li> + <li>任何後面接ASCII小寫a到z的dash(<code>U+002D</code>)都要被移除，接在後面的字母被換成相對應的大寫字母。</li> + <li>其他字元(包含其他dashes)都保持不變。</li> +</ul> + +<p>camelCase 到 dash-style: 與上述相反，將key值轉為資料屬性名稱，需根據以下規則：</p> + +<ul> + <li>限制: dash 不能馬上接任何ASCII小寫字母a到z(在轉換之前)。</li> + <li>加上前綴字 <code>data-</code> 。</li> + <li>任何ASCII大寫字母A到Z變成dash加上其相對應的小寫字母。</li> + <li>其他字元都保持不變。</li> +</ul> + +<p>上面所提的限制是為了確保兩個轉換方法互為相反。</p> + +<p>舉例來說，資料屬性名稱 <code>data-abc-def</code> 之對應key值為<code>abcDef</code>。</p> + +<p> </p> + +<h3 id="存取數值">存取數值</h3> + +<ul> + <li>資料屬性可以藉由camelCase名稱(key)像dataset物件屬性的方式設定或讀取，如element.dataset.keyname。</li> + <li>資料屬性也可以經由物件屬性[]語法的方式設定或讀取，如 <em>element.</em>dataset[<em>keyname</em>]。</li> +</ul> + +<h2 id="語法">語法</h2> + +<ul> + <li><em>string</em> = <em>element</em>.<strong>dataset</strong>.<em>camelCasedName</em>;</li> + <li><em>element.</em><strong>dataset</strong>.<em>camelCasedName</em> = <em>string</em>;</li> + <br> + <li><em>string</em> = <em>element</em>.<strong>dataset</strong>[<em>camelCasedName</em>];</li> + <li><em>element</em>.<strong>dataset</strong>[<em>camelCasedName</em>] = <em>string</em>;</li> + <br> + <li><em>自定的data屬性也可以直接從HTML設定，但是屬性名稱必須使用上述中的data- 語法。 </em></li> +</ul> + +<h2 id="範例">範例</h2> + +<pre class="brush: js"><div id="user" data-id="1234567890" data-user="johndoe" data-date-of-birth>John Doe</div> + +let el = document.querySelector('#user'); + +// el.id == 'user' +// el.dataset.id === '1234567890' +// el.dataset.user === 'johndoe' +// el.dataset.dateOfBirth === '' + +el.dataset.dateOfBirth = '1960-10-03'; // 設定 DOB. + +// 'someDataAttr' in el.dataset === false +el.dataset.someDataAttr = 'mydata'; +// 'someDataAttr' in el.dataset === true +</pre> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">備註</th> + </tr> + <tr> + <td>{{SpecName('HTML WHATWG', "dom.html#dom-dataset", "HTMLElement.dataset")}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>No change from latest snapshot, {{SpecName('HTML5.1')}}</td> + </tr> + <tr> + <td>{{SpecName('HTML5.1', "dom.html#dom-dataset", "HTMLElement.dataset")}}</td> + <td>{{Spec2('HTML5.1')}}</td> + <td>Snapshot of {{SpecName('HTML WHATWG')}}, no change from {{SpecName('HTML5 W3C')}}</td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', "dom.html#dom-dataset", "HTMLElement.dataset")}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>Snapshot of {{SpecName('HTML WHATWG')}}, initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{ CompatibilityTable() }}</p> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>功能</th> + <th>Chrome</th> + <th>Edge</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>基本支援</td> + <td>8</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{ CompatGeckoDesktop("6.0") }}</td> + <td>11</td> + <td>11.10</td> + <td>6</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>功能</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>基本支援</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile(6)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li>The HTML <a href="/en-US/docs/Web/HTML/Global_attributes/data-*"><strong>data-*</strong></a> class of global attributes.</li> + <li><a href="/en-US/docs/Learn/HTML/Howto/Use_data_attributes">Using data attributes</a></li> +</ul> diff --git a/files/zh-tw/web/api/htmlelement/index.html b/files/zh-tw/web/api/htmlelement/index.html new file mode 100644 index 0000000000..f0b3eb55e0 --- /dev/null +++ b/files/zh-tw/web/api/htmlelement/index.html @@ -0,0 +1,447 @@ +--- +title: HTMLElement +slug: Web/API/HTMLElement +translation_of: Web/API/HTMLElement +--- +<div> +<div>{{ APIRef("HTML DOM") }}</div> +</div> + +<div> </div> + +<p><strong><code>HTMLElement</code></strong> 介面表示了所有的 <a href="/docs/Web/HTML" title="/zh-TW/docs/Web/HTML">HTML</a> 元素。部分元素直接實作了此介面，其它則是實作繼承自 <code>HTMLElement</code> 的子介面。</p> + +<p>{{InheritanceDiagram}}</p> + +<h2 id="屬性">屬性</h2> + +<p><em>Inherits properties from its parent, {{domxref("Element")}}, and implements those from {{domxref("GlobalEventHandlers")}} and {{domxref("TouchEventHandlers")}}.</em></p> + +<dl> + <dt>{{domxref("HTMLElement.accessKey")}}</dt> + <dd>Is a {{domxref("DOMString")}} representing the access key assigned to the element.</dd> + <dt>{{domxref("HTMLElement.accessKeyLabel")}} {{readonlyInline}}</dt> + <dd>Returns a {{domxref("DOMString")}} containing the element's assigned access key.</dd> + <dt>{{domxref("HTMLElement.contentEditable")}}</dt> + <dd>Is a {{domxref("DOMString")}}, where a value of <code>"true"</code> means the element is editable and a value of <code>"false"</code> means it isn't.</dd> + <dt>{{domxref("HTMLElement.isContentEditable")}} {{readonlyInline}}</dt> + <dd>Returns a {{domxref("Boolean")}} that indicates whether or not the content of the element can be edited.</dd> + <dt>{{domxref("HTMLElement.contextMenu")}}</dt> + <dd>Is a {{domxref("HTMLMenuElement")}} representing the contextual menu associated with the element. It may be <code>null</code>.</dd> + <dt>{{domxref("HTMLElement.dataset")}} {{readonlyInline}}</dt> + <dd>Returns a {{domxref("DOMStringMap")}} with which script can read and write the element's <a href="/en-US/docs/Web/Guide/HTML/Using_data_attributes">custom data attributes</a> (<code>data-*</code>) .</dd> + <dt>{{domxref("HTMLElement.dir")}}</dt> + <dd>Is a {{domxref("DOMString")}}, reflecting the <code>dir</code> global attribute, representing the directionality of the element. Possible values are <code>"ltr"</code>, <code>"rtl"</code>, and <code>"auto"</code>.</dd> + <dt>{{domxref("HTMLElement.draggable")}}</dt> + <dd>Is a {{jsxref("Boolean")}} indicating if the element can be dragged.</dd> + <dt>{{domxref("HTMLElement.dropzone")}} {{readonlyInline}}</dt> + <dd>Returns a {{domxref("DOMSettableTokenList")}} reflecting the <code>dropzone</code> global attribute and describing the behavior of the element regarding a drop operation.</dd> + <dt>{{domxref("HTMLElement.hidden")}}</dt> + <dd>Is a {{jsxref("Boolean")}} indicating if the element is hidden or not.</dd> + <dt>{{domxref("HTMLElement.itemScope")}} {{experimental_inline}}</dt> + <dd>Is a {{jsxref("Boolean")}} representing the item scope.</dd> + <dt>{{domxref("HTMLElement.itemType")}} {{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns a {{domxref("DOMSettableTokenList")}}…</dd> + <dt>{{domxref("HTMLElement.itemId")}} {{experimental_inline}}</dt> + <dd>Is a {{domxref("DOMString")}} representing the item ID.</dd> + <dt>{{domxref("HTMLElement.itemRef")}} {{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns a {{domxref("DOMSettableTokenList")}}…</dd> + <dt>{{domxref("HTMLElement.itemProp")}} {{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns a {{domxref("DOMSettableTokenList")}}…</dd> + <dt>{{domxref("HTMLElement.itemValue")}} {{experimental_inline}}</dt> + <dd>Returns a {{jsxref("Object")}} representing the item value.</dd> + <dt>{{domxref("HTMLElement.lang")}}</dt> + <dd>Is a {{domxref("DOMString")}} representing the language of an element's attributes, text, and element contents.</dd> + <dt>{{domxref("HTMLElement.offsetHeight")}} {{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns a <code>double</code> containing the height of an element, relative to the layout.</dd> + <dt>{{domxref("HTMLElement.offsetLeft")}}{{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns a <code>double</code>, the distance from this element's left border to its <code>offsetParent</code>'s left border.</dd> + <dt>{{domxref("HTMLElement.offsetParent")}}{{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns a {{domxref("Element")}} that is the element from which all offset calculations are currently computed.</dd> + <dt>{{domxref("HTMLElement.offsetTop")}}{{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns a <code>double</code>, the distance from this element's top border to its <code>offsetParent</code>'s top border.</dd> + <dt>{{domxref("HTMLElement.offsetWidth")}}{{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns a <code>double</code> containing the width of an element, relative to the layout.</dd> + <dt>{{domxref("HTMLElement.properties")}} {{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns a {{domxref("HTMLPropertiesCollection")}}…</dd> + <dt>{{domxref("HTMLElement.spellcheck")}}{{ gecko_minversion_inline("1.9")}}</dt> + <dd>Is a {{jsxref("Boolean")}} that controls <a href="/en-US/docs/HTML/Controlling_spell_checking_in_HTML_forms" title="en/Controlling_spell_checking_in_HTML_forms">spell-checking</a>. It is present on all HTML elements, though it doesn't have an effect on all of them.</dd> + <dt>{{domxref("HTMLElement.style")}}</dt> + <dd>Is a {{domxref("CSSStyleDeclaration")}}, an object representing the declarations of an element's style attributes.</dd> + <dt>{{domxref("HTMLElement.tabIndex")}}</dt> + <dd>Is a <code>long</code> representing the position of the element in the tabbing order.</dd> + <dt>{{domxref("HTMLElement.title")}}</dt> + <dd>Is a {{domxref("DOMString")}} containing the text that appears in a popup box when mouse is over the element.</dd> + <dt>{{domxref("HTMLElement.translate")}} {{experimental_inline}}</dt> + <dd>Is a {{jsxref("Boolean")}} representing the translation.</dd> +</dl> + +<h3 id="事件處理器">事件處理器</h3> + +<p>Most events properties, of the form <code>onXYZ</code>, are defined on the {{domxref("GlobalEventHandlers")}} or {{domxref("TouchEventHandlers")}}, implemented by <code>HTMLElement</code>. A few more are specific to <code>HTMLElement</code>.</p> + +<dl> + <dt>{{ domxref("HTMLElement.oncopy") }} {{ non-standard_inline() }}</dt> + <dd>Returns the event handling code for the <code>copy</code> event ({{bug("280959")}}).</dd> + <dt>{{ domxref("HTMLElement.oncut") }} {{ non-standard_inline() }}</dt> + <dd>Returns the event handling code for the <code>cut</code> event ({{bug("280959")}}).</dd> + <dt>{{ domxref("HTMLElement.onpaste") }} {{ non-standard_inline() }}</dt> + <dd>Returns the event handling code for the <code>paste</code> event ({{bug("280959")}}).</dd> + <dt>{{domxref("TouchEventHandlers.ontouchstart")}} {{non-standard_inline}}</dt> + <dd>Returns the event handling code for the {{event("touchstart")}} event.</dd> + <dt>{{domxref("TouchEventHandlers.ontouchend")}} {{non-standard_inline}}</dt> + <dd>Returns the event handling code for the {{event("touchend")}} event.</dd> + <dt>{{domxref("TouchEventHandlers.ontouchmove")}} {{non-standard_inline}}</dt> + <dd>Returns the event handling code for the {{event("touchmove")}} event.</dd> + <dt>{{domxref("TouchEventHandlers.ontouchenter")}} {{non-standard_inline}}</dt> + <dd>Returns the event handling code for the {{event("touchenter")}} event.</dd> + <dt>{{domxref("TouchEventHandlers.ontouchleave")}} {{non-standard_inline}}</dt> + <dd>Returns the event handling code for the {{event("touchleave")}} event.</dd> + <dt>{{domxref("TouchEventHandlers.ontouchcancel")}} {{non-standard_inline}}</dt> + <dd>Returns the event handling code for the {{event("touchcancel")}} event.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>Inherits methods from its parent, {{domxref("Element")}}.</em></p> + +<dl> + <dt>{{domxref("HTMLElement.blur()")}}</dt> + <dd>Removes keyboard focus from the currently focused element.</dd> + <dt>{{domxref("HTMLElement.click()")}}</dt> + <dd>Sends a mouse click event to the element.</dd> + <dt>{{domxref("HTMLElement.focus()")}}</dt> + <dd>Makes the element the current keyboard focus.</dd> + <dt>{{domxref("HTMLElement.forceSpellCheck()")}} {{experimental_inline}}</dt> + <dd>Runs the spell checker on the element's contents.</dd> +</dl> + +<h2 id="規範">規範</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('CSSOM View', '#extensions-to-the-htmlelement-interface', 'HTMLElement')}}</td> + <td>{{Spec2('CSSOM View')}}</td> + <td>Added the following properties: <code>offsetParent</code>, <code>offsetTop</code>, <code>offsetLeft</code>, <code>offsetWidth</code>, and <code>offsetHeight</code>.</td> + </tr> + <tr> + <td>{{SpecName('HTML WHATWG', 'elements.html#htmlelement', 'HTMLElement')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>Added the following properties: <code>translate</code>, <code>itemScope</code>, <code>itemType</code>, <code>itemId</code>, <code>itemRef</code>, <code>itemProp</code>, <code>properties</code>, and <code>itemValue</code>.<br> + Added the following method: <code>forceSpellcheck()</code>.<br> + Moved the <code>onXYZ</code> attributes to the {{domxref("GlobalEventHandlers")}} interface and added an inheritance from it.</td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', 'dom.html#htmlelement', 'HTMLElement')}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>Added the following properties: <code>dataset</code>, <code>hidden</code>, <code>tabindex</code>, <code>accessKey</code>, <code>accessKeyLabel</code>, <code>draggable</code>, <code>dropzone</code>, <code>contentEditable</code>, <code>isContentEditable</code>, <code>contextMenu</code>, <code>spellcheck</code>, <code>commandType</code>, <code>commandLabel</code>, <code>commandIcon</code>, <code>commandHidden</code>, <code>commandDisabled</code>, <code>commandChecked</code>, <code>style</code>, and all the <code>onXYZ</code> properties.<br> + Moved the <code>id</code> and <code>className</code> properties to the {{domxref("Element")}} interface.</td> + </tr> + <tr> + <td>{{SpecName('DOM2 HTML', 'html.html#ID-011100101', 'HTMLElement')}}</td> + <td>{{Spec2('DOM2 HTML')}}</td> + <td>No change from {{SpecName('DOM2 HTML')}}</td> + </tr> + <tr> + <td>{{SpecName('DOM1', 'level-one-html.html#ID-011100101', 'HTMLElement')}}</td> + <td>{{Spec2('DOM1')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Firefox (Gecko)</th> + <th>Chrome</th> + <th>Edge</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatGeckoDesktop("1.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.accessKey", "accessKey")}}</td> + <td>{{CompatGeckoDesktop("5.0")}}</td> + <td>17.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>6.0</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.accessKeyLabel", "accessKeyLabel")}}</td> + <td>{{CompatGeckoDesktop("8.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}{{WebkitBug(72715)}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.blur()", "blur()")}}</td> + <td>{{CompatGeckoDesktop("5.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>9</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.click()", "click()")}}</td> + <td>{{CompatGeckoDesktop("5.0")}}</td> + <td>{{CompatUnknown}}9</td> + <td>{{CompatVersionUnknown}}</td> + <td>9</td> + <td>{{CompatUnknown}}</td> + <td>6.0</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.dataset", "dataset")}}</td> + <td>{{CompatGeckoDesktop("6.0")}}</td> + <td>8</td> + <td>{{CompatVersionUnknown}}</td> + <td>11</td> + <td>11.10</td> + <td>5.1</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.focus()", "focus()")}}</td> + <td>{{CompatGeckoDesktop("5.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>9</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.contentEditable", "contentEditable")}}</td> + <td>{{CompatGeckoDesktop("1.9")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>5.5</td> + <td>9</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.spellcheck", "spellcheck")}}</td> + <td>{{CompatGeckoDesktop("1.8.1")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.style", "style")}}</td> + <td>{{CompatVersionUnknown}} (returns a {{domxref("CSS2Properties")}}, rather than a {{domxref("CSSStyleDeclaration")}})</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.forceSpellCheck", "forceSpellCheck()")}} {{experimental_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.draggable", "draggable")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>12.0</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.dropzone", "dropzone")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>12.0</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.offsetLeft", "offsetLeft")}}, {{domxref("HTMLElement.offsetTop", "offsetTop")}}, {{domxref("HTMLElement.offsetParent", "offsetParent")}}, {{domxref("HTMLElement.offsetHeight", "offsetHeight")}} and {{domxref("HTMLElement.offsetWidth", "offsetWidth")}} {{experimental_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.translate", "translate")}} {{experimental_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.itemScope", "itemScope")}}, {{domxref("HTMLElement.itemType", "itemType")}}, {{domxref("HTMLElement.itemRef", "itemRef")}}, {{domxref("HTMLElement.itemId", "itemId")}}, {{domxref("HTMLElement.itemProp", "itemProp")}}, and {{domxref("HTMLElement.itemValue", "itemValue")}} {{experimental_inline}}</td> + <td>{{CompatGeckoDesktop("6.0")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>11.60<br> + (Removed in Opera 15)</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.properties", "properties")}} {{experimental_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.ontouchstart")}}, {{domxref("HTMLElement.ontouchend")}}, {{domxref("HTMLElement.ontouchmove")}}, {{domxref("HTMLElement.ontouchenter")}}, {{domxref("HTMLElement.ontouchleave")}}, and {{domxref("HTMLElement.ontouchcancel")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.oncopy")}}, {{domxref("HTMLElement.oncut")}}, and {{domxref("HTMLElement.onpaste")}} {{Non-standard_inline}}</td> + <td>{{CompatGeckoDesktop("1.9")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Firefox Mobile (Gecko)</th> + <th>Android</th> + <th>Edge</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td> + <p>{{CompatGeckoMobile("1.0")}}</p> + </td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.accessKey", "accessKey")}}</td> + <td>{{CompatGeckoMobile("5.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.accessKeyLabel", "accessKeyLabel")}}</td> + <td>{{CompatGeckoMobile("8.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.blur()", "blur()")}}</td> + <td>{{CompatGeckoMobile("5.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.click()", "click()")}}</td> + <td>{{CompatGeckoMobile("5.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.dataset", "dataset")}}</td> + <td>{{CompatGeckoMobile("6.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.focus()", "focus()")}}</td> + <td>{{CompatGeckoMobile("5.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>{{domxref("HTMLElement.oncopy")}}, {{domxref("HTMLElement.oncut")}}, and {{domxref("HTMLElement.onpaste")}} {{Non-standard_inline}}</td> + <td>{{CompatGeckoMobile("1.9")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("Element")}}</li> +</ul> diff --git a/files/zh-tw/web/api/htmlelement/lang/index.html b/files/zh-tw/web/api/htmlelement/lang/index.html new file mode 100644 index 0000000000..ff546e3ca9 --- /dev/null +++ b/files/zh-tw/web/api/htmlelement/lang/index.html @@ -0,0 +1,59 @@ +--- +title: HTMLElement.lang +slug: Web/API/HTMLElement/lang +tags: + - API + - HTML DOM + - HTMLElement + - NeedsBrowserCompatibility + - NeedsUpdate + - Property + - Reference +translation_of: Web/API/HTMLElement/lang +--- +<div>{{ APIRef("HTML DOM") }}</div> + +<p><code><strong>HTMLElement.lang</strong></code> 屬性（{{Glossary("property")}}）可以讀取或設定一個表示元素之語系的標籤屬性（{{Glossary("attribute")}}）值。</p> + +<p><code>HTMLElement.lang</code> 屬性所回傳的語系代碼定義於網際網路工程任務小組（IETF）的 <a class="external" href="https://www.ietf.org/rfc/bcp/bcp47.txt"><em>Tags for Identifying Languages (BCP47)</em></a> 文件中。常見的例子如 "en" 代表英語、"ja" 代表日語、"es" 代表西班牙語等等。此標籤屬性的預設值為 <code>unknown</code>。請留意，雖然此標籤屬性於個別層級的元素上是有效的，但大部分都設定於文件的根元素。</p> + +<p><code>HTMLElement.lang</code> 屬性只對 <code>lang</code> 標籤屬性有作用，而不是 <code>xml:lang</code>。</p> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox">var <var>languageUsed</var> = elementNodeReference.lang; // Get the value of lang +elementNodeReference.lang = <var>NewLanguage</var>; // Set new value for lang +</pre> + +<p><var>languageUsed</var> is a string variable that gets the language in which the text of the current element is written. <var>NewLanguage</var> is a string variable with its value setting the language in which the text of the current element is written.</p> + +<h2 id="Example" name="Example">範例</h2> + +<pre class="brush: js">// this snippet compares the base language and +// redirects to another url based on language +if (document.documentElement.lang === "en") { + window.location.href = "Some_document.html.en"; +} else if (document.documentElement.lang === "ru") { + window.location.href = "Some_document.html.ru"; +}</pre> + +<h2 id="Specification" name="Specification">規範</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('DOM2 HTML', 'html.html#ID-59132807', 'lang')}}</td> + <td>{{Spec2('DOM2 HTML')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<p> </p> diff --git a/files/zh-tw/web/api/htmlelement/style/index.html b/files/zh-tw/web/api/htmlelement/style/index.html new file mode 100644 index 0000000000..e9e6d1171a --- /dev/null +++ b/files/zh-tw/web/api/htmlelement/style/index.html @@ -0,0 +1,79 @@ +--- +title: HTMLElement.style +slug: Web/API/HTMLElement/style +translation_of: Web/API/ElementCSSInlineStyle/style +--- +<div>{{ APIRef("HTML DOM") }}</div> + +<p>The <code><strong>HTMLElement.style</strong></code> property is used to get as well as set the <strong>inline </strong>style of an element. While getting, it returns a <a href="/en-US/docs/DOM/CSSStyleDeclaration" title="DOM/CSSStyleDeclaration"><code>CSSStyleDeclaration</code></a> object that contains a list of all styles properties for that element with values assigned for the attributes that are defined in the element's <strong>inline</strong> <a href="/en-US/docs/Web/HTML/Global_attributes#style"><code>style</code> attribute</a>. See the <a href="/en-US/docs/Web/CSS/CSS_Properties_Reference" title="/en-US/docs/Web/CSS/CSS_Properties_Reference">CSS Properties Reference</a> for a list of the CSS properties accessible via <code>style</code>.The <code>style</code> property has the same (and highest) priority in the CSS cascade as an inline style declaration set via the <code>style</code> attribute.</p> + +<h3 id="設定_styles">設定 <code>styles</code></h3> + +<p>Styles can be set by assigning a string directly to the <code>style</code> property (as in<code> elt.style = "color: blue;") </code>or by assigning values to the properties of <code>style</code><code>. </code>For adding specific styles to an element without altering other style values, it is preferred to use the individual properties of <code>style</code> (as in<code> elt.style.color = '...' </code>) as using<code> elt.style.cssText = '...' or elt.setAttribute('style', '...')</code> sets the complete inline style for the element by overriding the existing inline styles. Note that the property names are in camel-case and not kebab-case while setting the style using <code>elt.style.<property> (</code>i.e.<code> elt.style.fontSize, </code>not<code> elt.style.font-size)</code></p> + +<h2 id="範例">範例</h2> + +<pre class="brush:js"><code>// Set multiple styles in a single statement +elt.style.cssText = "color: blue; border: 1px solid black"; +// OR +elt.setAttribute("style", "color:red; border: 1px solid blue;");</code> + + +elt.style.color = "blue"; // Set specific style while leaving other inline style values untouched +</pre> + +<h3 id="取得樣式資訊">取得樣式資訊</h3> + +<p>The <code>style</code> property is not useful for completely learning about the styles applied on the element, since it represents only the CSS declarations set in the element's inline <code>style</code> attribute, not those that come from style rules elsewhere, such as style rules in the {{HTMLElement("head")}} section, or external style sheets. To get the values of all CSS properties for an element you should use {{domxref("window.getComputedStyle()")}} instead.</p> + +<p>The following code snippet demonstrates the difference between the values obtained using the element's <code>style </code>property and that obtained using the <code>computedStyle()</code> method:</p> + +<pre class="brush: html"><!DOCTYPE HTML> +<html> + <body style="font-weight:bold;"> + + <div style="color:red" id="myElement">..</div> + + </body> +</html> +</pre> + +<pre class="brush:js">var element = document.getElementById("myElement"); +var out = ""; +var elementStyle = element.style; +var computedStyle = window.getComputedStyle(element, null); + +for (prop in elementStyle) { + if (elementStyle.hasOwnProperty(prop)) { + out += " " + prop + " = '" + elementStyle[prop] + "' > '" + computedStyle[prop] + "'\n"; + } +} +console.log(out) +</pre> + +<p>The output would be something like:</p> + +<pre>... +fontWeight = '' > 'bold' +color = 'red' > 'rgb(255, 0, 0)' +...</pre> + +<p>Note the presence of the value "bold" for font-weight in the computed style and the absence of it in the element's style property</p> + +<h2 id="Specification" name="Specification">規範</h2> + +<p><a class="external" href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-ElementCSSInlineStyle">DOM Level 2 Style: ElementCSSInlineStyle.style</a></p> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<div class="note"> +<p><strong>Note:</strong> Starting in {{Gecko("2.0")}}, you can set SVG properties' values using the same shorthand syntax. For example:</p> + +<pre><code>element.style.fill = 'lime';</code></pre> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/en-US/docs/DOM/Using_dynamic_styling_information" title="DOM/Using dynamic styling information">Using dynamic styling information</a></li> +</ul> diff --git a/files/zh-tw/web/api/htmlformelement/index.html b/files/zh-tw/web/api/htmlformelement/index.html new file mode 100644 index 0000000000..614eebbad2 --- /dev/null +++ b/files/zh-tw/web/api/htmlformelement/index.html @@ -0,0 +1,245 @@ +--- +title: HTMLFormElement +slug: Web/API/HTMLFormElement +translation_of: Web/API/HTMLFormElement +--- +<div>{{APIRef("HTML DOM")}}</div> + +<p><strong><code>HTMLFormElement</code></strong> 介面提供了建立及修改 {{HTMLElement("form")}} 元素的方法。<br> + <strong>document.forms</strong> - returns an array of HTMLFormElement objects referencing all forms on the page.<br> + <strong>document.forms[index] </strong>- returns an HTMLFormElement object referencing the form at the specified index.<br> + <strong>document.forms['id'] </strong>- returns an HTMLFormElement object referencing the form with the specified id.<br> + <strong>document.forms['name'] </strong>- returns an HTMLFormElement object referencing the form with the specified name.</p> + +<p>{{InheritanceDiagram(600,120)}}</p> + +<h2 id="屬性">屬性</h2> + +<p><em>This interface also inherits properties from its parent, {{domxref("HTMLElement")}}.</em></p> + +<dl> + <dt>{{domxref("HTMLFormElement.elements")}}{{ReadOnlyInline}}</dt> + <dd>A {{domxref("HTMLFormControlsCollection")}} holding all form controls belonging to this form element.</dd> + <dt>{{domxref("HTMLFormElement.length")}}{{ReadOnlyInline}}</dt> + <dd>A <code>long</code> reflecting the number of controls in the form.</dd> + <dt>{{domxref("HTMLFormElement.name")}}</dt> + <dd>A {{domxref("DOMString")}} reflecting the value of the form's {{ htmlattrxref("name", "form") }} HTML attribute, containing the name of the form.</dd> + <dt>{{domxref("HTMLFormElement.method")}}</dt> + <dd>A {{domxref("DOMString")}} reflecting the value of the form's {{ htmlattrxref("method", "form") }} HTML attribute, indicating the HTTP method used to submit the form. Only specified values can be set.</dd> + <dt>{{domxref("HTMLFormElement.target")}}</dt> + <dd>A {{domxref("DOMString")}} reflecting the value of the form's {{ htmlattrxref("target", "form") }} HTML attribute, indicating where to display the results received from submitting the form.</dd> + <dt>{{domxref("HTMLFormElement.action")}}</dt> + <dd>A {{domxref("DOMString")}} reflecting the value of the form's {{ htmlattrxref("action", "form") }} HTML attribute, containing the URI of a program that processes the information submitted by the form.</dd> + <dt>{{domxref("HTMLFormElement.encoding")}} or {{domxref("HTMLFormElement.enctype")}}</dt> + <dd>A {{domxref("DOMString")}} reflecting the value of the form's {{ htmlattrxref("enctype", "form") }} HTML attribute, indicating the type of content that is used to transmit the form to the server. Only specified values can be set. The two methods are synonyms.</dd> + <dt>{{domxref("HTMLFormElement.acceptCharset")}}</dt> + <dd>A {{domxref("DOMString")}} reflecting the value of the form's {{ htmlattrxref("accept-charset", "form") }} HTML attribute, representing the character encoding that the server accepts.</dd> + <dt>{{domxref("HTMLFormElement.autocomplete")}}</dt> + <dd>A {{domxref("DOMString")}} reflecting the value of the form's {{ htmlattrxref("autocomplete", "form") }} HTML attribute, indicating whether the controls in this form can have their values automatically populated by the browser.</dd> + <dt>{{domxref("HTMLFormElement.noValidate")}}</dt> + <dd>A {{jsxref("Boolean")}} reflecting the value of the form's {{ htmlattrxref("novalidate", "form") }} HTML attribute, indicating whether the form should not be validated.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>This interface also inherits methods from its parent, {{domxref("HTMLElement")}}.</em></p> + +<dl> + <dt>{{domxref("HTMLFormElement.submit()")}}</dt> + <dd>Submits the form to the server.</dd> + <dt>{{domxref("HTMLFormElement.reset()")}}</dt> + <dd>Resets the form to its initial state.</dd> + <dt>{{domxref("HTMLFormElement.checkValidity()")}}</dt> + <dd>Returns <code>true</code> if the element's child controls are subject to constraint validation and satisfy those contraints; returns <code>false</code> if some controls do not satisfy their constraints. Fires an event named {{event("invalid")}} at any control that does not satisfy its constraints; such controls are considered invalid if the event is not canceled. It is up to the programmer to decide how to respond to <code>false</code>.</dd> + <dt>{{domxref("HTMLFormElement.reportValidity()")}}</dt> + <dd>Returns <code>true</code> if the element's child controls satisfy their validation constraints. When <code>false</code> is returned, cancelable {{Event("invalid")}} events are fired for each invalid child and validation problems are reported to the user.</dd> + <dt>{{domxref("HTMLFormElement.requestAutocomplete()")}}</dt> + <dd>Triggers a native browser interface to assist the user in completing the fields which have an <a href="https://html.spec.whatwg.org/#autofill-field-name">autofill field name</a> value that is not <code>off</code> or <code>on</code>. The form will receive an event once the user has finished with the interface, the event will either be {{event("autocomplete")}} when the fields have been filled or {{event("autocompleteerror")}} when there was a problem.</dd> +</dl> + +<h2 id="範例">範例</h2> + +<p>Create a new form element, modify its attributes and submit it:</p> + +<pre class="brush: js">var f = document.createElement("form");// Create a form +document.body.appendChild(f); // Add it to the document body +f.action = "/cgi-bin/some.cgi"; // Add action and method attributes +f.method = "POST" +f.submit(); // Call the form's submit method +</pre> + +<p>Extract information from a form element and set some of its attributes:</p> + +<pre class="brush: html"><form name="formA" id="formA" action="/cgi-bin/test" method="POST"> + <p>Click "Info" for form details; "Set" to change settings.</p> + <p> + <input type="button" value="info" onclick="getFormInfo();"> + <input type="button" value="set" onclick="setFormInfo(this.form);"> + <input type="reset" value="reset"><br> + <textarea id="tex" style="height:15em; width:20em"></textarea> + </p> +</form> + +<script type="text/javascript"> + function getFormInfo(){ + var info; + var f = document.forms["formA"]; //Get a reference to the form via id. + info = "elements: " + f.elements + "\n" + + "length: " + f.length + "\n" + + "name: " + f.name + "\n" + + "charset: " + f.acceptCharset+ "\n" + + "action: " + f.action + "\n" + + "enctype: " + f.enctype + "\n" + + "encoding: " + f.encoding + "\n" + + "method: " + f.method + "\n" + + "target: " + f.target; + document.forms["formA"].elements['tex'].value = info; + } + function setFormInfo(f){ //Argument is a reference to the form. + f.method = "GET"; + f.action = "/cgi-bin/evil_executable.cgi"; + f.name = "totally_new"; + } +</script> +</pre> + +<p>Submit a form in a <a href="/en-US/docs/Web/API/Window/open">popup window</a>:</p> + +<pre class="brush: html"><!doctype html> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> +<title>MDN Example</title> +<script type="text/javascript"> +function popupSend (oFormElement) { + if (oFormElement.method && oFormElement.method.toLowerCase() !== "get") { + console.error("This script supports the GET method only."); + return; + } + var oField, sFieldType, nFile, sSearch = ""; + for (var nItem = 0; nItem < oFormElement.elements.length; nItem++) { + oField = oFormElement.elements[nItem]; + if (!oField.hasAttribute("name")) { continue; } + sFieldType = oField.nodeName.toUpperCase() === "INPUT" ? oField.getAttribute("type").toUpperCase() : "TEXT"; + if (sFieldType === "FILE") { + for (nFile = 0; nFile < oField.files.length; sSearch += "&" + escape(oField.name) + "=" + escape(oField.files[nFile++].name)); + } else if ((sFieldType !== "RADIO" && sFieldType !== "CHECKBOX") || oField.checked) { + sSearch += "&" + escape(oField.name) + "=" + escape(oField.value); + } + } + open(oFormElement.action.replace(/(?:\?.*)?$/, sSearch.replace(/^&/, "?")), "submit-" + (oFormElement.name || Math.floor(Math.random() * 1e6)), "resizable=yes,scrollbars=yes,status=yes"); +} +</script> + +</head> + +<body> + +<form name="yourForm" action="test.php" method="get" onsubmit="popupSend(this); return false;"> + <p>First name: <input type="text" name="firstname" /><br /> + Last name: <input type="text" name="lastname" /><br /> + Password: <input type="password" name="pwd" /><br /> + <input type="radio" name="sex" value="male" /> Male <input type="radio" name="sex" value="female" /> Female</p> + <p><input type="checkbox" name="vehicle" value="Bike" />I have a bike<br /> + <input type="checkbox" name="vehicle" value="Car" />I have a car</p> + <p><input type="submit" value="Submit" /></p> +</form> + +</body> +</html></pre> + +<h3 id="使用_XMLHttpRequest_提交表單及上傳檔案">使用 <code>XMLHttpRequest</code> 提交表單及上傳檔案</h3> + +<p>If you want to know how to serialize and submit a form using the {{domxref("XMLHttpRequest")}} API, please read <a href="/en-US/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest#Submitting_forms_and_uploading_files">this paragraph</a>.</p> + +<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('HTML WHATWG', "forms.html#the-form-element", "HTMLFormElement")}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>The following method has been added: <code>requestAutocomplete()</code>.</td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', "forms.html#the-form-element", "HTMLFormElement")}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>The elements properties returns an {{domxref("HTMLFormControlsCollection")}} instead of a raw {{domxref("HTMLCollection")}}. This is mainly a technical change. The following method has been added: <code>checkValidity()</code>. The following properties have been added: <code>autocomplete</code>, <code>noValidate</code>, and <code>encoding</code>.</td> + </tr> + <tr> + <td>{{SpecName('DOM2 HTML', 'html.html#ID-40002357', 'HTMLFormElement')}}</td> + <td>{{Spec2('DOM2 HTML')}}</td> + <td>No change</td> + </tr> + <tr> + <td>{{SpecName('DOM1', 'level-one-html.html#ID-40002357', 'HTMLFormElement')}}</td> + <td>{{Spec2('DOM1')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(1.0)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile(1.0)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li>The HTML element implementing this interface: {{ HTMLElement("form") }}.</li> +</ul> diff --git a/files/zh-tw/web/api/htmlformelement/submit_event/index.html b/files/zh-tw/web/api/htmlformelement/submit_event/index.html new file mode 100644 index 0000000000..6c5b030f7c --- /dev/null +++ b/files/zh-tw/web/api/htmlformelement/submit_event/index.html @@ -0,0 +1,60 @@ +--- +title: submit +slug: Web/API/HTMLFormElement/submit_event +translation_of: Web/API/HTMLFormElement/submit_event +--- +<p><code>submit</code> 事件會在表單送出時觸發。</p> + +<p>要注意的是，<code>submit</code> 事件<strong>只會</strong>在 <a href="/en-US/docs/Web/HTML/Element/form">form element</a> 上觸發， <a href="/en-US/docs/Web/HTML/Element/button">button</a> 或是 <a href="/en-US/docs/Web/HTML/Element/input">submit input</a> 則不會觸發。（送出的是「表單」，而非「按鈕」）</p> + +<h2 id="基本資料">基本資料</h2> + +<dl> + <dt style="float: left; text-align: right; width: 120px;">定義規範</dt> + <dd style="margin: 0 0 0 120px;"><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/association-of-controls-and-forms.html#form-submission-algorithm">HTML5</a></dd> + <dt style="float: left; text-align: right; width: 120px;">Interface</dt> + <dd style="margin: 0 0 0 120px;">{{domxref("Event")}}</dd> + <dt style="float: left; text-align: right; width: 120px;">Bubbles</dt> + <dd style="margin: 0 0 0 120px;">是 <br> + 雖說在規範上這是個不 bubble 的事件</dd> + <dt style="float: left; text-align: right; width: 120px;">Cancelable</dt> + <dd style="margin: 0 0 0 120px;">是</dd> + <dt style="float: left; text-align: right; width: 120px;">Target</dt> + <dd style="margin: 0 0 0 120px;">Element</dd> + <dt style="float: left; text-align: right; width: 120px;">默認行動</dt> + <dd style="margin: 0 0 0 120px;">修改（傳送表單內容至伺服器）。</dd> +</dl> + +<h2 id="屬性">屬性</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Property</th> + <th scope="col">Type</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>target</code> {{readonlyInline}}</td> + <td>{{domxref("EventTarget")}}</td> + <td>The event target (the topmost target in the DOM tree).</td> + </tr> + <tr> + <td><code>type</code> {{readonlyInline}}</td> + <td>{{domxref("DOMString")}}</td> + <td>The type of event.</td> + </tr> + <tr> + <td><code>bubbles</code> {{readonlyInline}}</td> + <td>{{jsxref("Boolean")}}</td> + <td>Whether the event normally bubbles or not.</td> + </tr> + <tr> + <td><code>cancelable</code> {{readonlyInline}}</td> + <td>{{jsxref("Boolean")}}</td> + <td>Whether the event is cancellable or not.</td> + </tr> + </tbody> +</table> diff --git a/files/zh-tw/web/api/htmlimageelement/index.html b/files/zh-tw/web/api/htmlimageelement/index.html new file mode 100644 index 0000000000..0bf5e96953 --- /dev/null +++ b/files/zh-tw/web/api/htmlimageelement/index.html @@ -0,0 +1,408 @@ +--- +title: HTMLImageElement +slug: Web/API/HTMLImageElement +translation_of: Web/API/HTMLImageElement +--- +<div>{{APIRef("HTML DOM")}}</div> + +<p><strong><code>HTMLImageElement</code></strong> 介面提供了特殊的屬性及方法以用來操作 {{HTMLElement("img")}} 元素的畫面佈局與外觀呈現。</p> + +<p>{{InheritanceDiagram(600,120)}}</p> + +<h2 id="屬性">屬性</h2> + +<p><em>Inherits properties from its parent, {{domxref("HTMLElement")}}.</em></p> + +<dl> + <dt>{{domxref("HTMLImageElement.align")}} {{obsolete_inline}}</dt> + <dd>Is a {{domxref("DOMString")}} indicating the alignment of the image with respect to the surrounding context.</dd> + <dt>{{domxref("HTMLImageElement.alt")}}</dt> + <dd>Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("alt", "img")}} HTML attribute, thus indicating fallback context for the image.</dd> + <dt>{{domxref("HTMLImageElement.border")}} {{obsolete_inline}}</dt> + <dd>Is a {{domxref("DOMString")}} that is responsible for the width of the border surrounding the image. This is now deprecated and the CSS {{cssxref("border")}} property should be used instead.</dd> + <dt>{{domxref("HTMLImageElement.complete")}} {{readonlyInline}}</dt> + <dd>Returns a {{domxref("Boolean")}} that is <code>true</code> if the browser has finished fetching the image, whether successful or not. It also shows true, if the image has no {{domxref("HTMLImageElement.src", "src")}} value.</dd> + <dt>{{domxref("HTMLImageElement.crossOrigin")}}</dt> + <dd>Is a {{domxref("DOMString")}} representing the CORS setting for this image element. See <a href="/en-US/docs/HTML/CORS_settings_attributes">CORS settings attributes</a> for further details.</dd> + <dt>{{domxref("HTMLImageElement.currentSrc")}} {{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns a {{domxref("DOMString")}} representing the URL to the currently displayed image (which may change, for example in response to media queries).</dd> + <dt>{{domxref("HTMLImageElement.height")}}</dt> + <dd>一個反映了 HTML <code>img</code> 元素之 {{htmlattrxref("height", "img")}} 屬性的無符號（<code>unsigned</code>）整數，表示圖片經渲染後的高度（CSS pixels）。</dd> + <dt>{{domxref("HTMLImageElement.hspace")}} {{obsolete_inline}}</dt> + <dd>Is a <code>long</code> representing the space on either side of the image.</dd> + <dt>{{domxref("HTMLImageElement.isMap")}}</dt> + <dd>Is a {{domxref("Boolean")}} that reflects the {{htmlattrxref("ismap", "img")}} HTML attribute, indicating that the image is part of a server-side image map.</dd> + <dt>{{domxref("HTMLImageElement.longDesc")}} {{obsolete_inline}}</dt> + <dd>Is a {{domxref("DOMString")}} representing the URI of a long description of the image.</dd> + <dt>{{domxref("HTMLImageElement.lowSrc")}} {{obsolete_inline}}</dt> + <dd>Is a {{domxref("DOMString")}} that refers to a low-quality (but faster to load) copy of the image.</dd> + <dt>{{domxref("HTMLImageElement.name")}} {{obsolete_inline}}</dt> + <dd>Is a {{domxref("DOMString")}} representing the name of the element.</dd> + <dt>{{domxref("HTMLImageElement.naturalHeight")}} {{readonlyInline}}</dt> + <dd>回傳一個代表圖片固有高度（CSS pixels）的無符號（<code>unsigned</code>）整數，如果無法取得則回傳 <code>0</code>。</dd> + <dt>{{domxref("HTMLImageElement.naturalWidth")}} {{readonlyInline}}</dt> + <dd>回傳一個代表圖片固有寬度（CSS pixels）的無符號（<code>unsigned</code>）整數，如果無法取得則回傳 <code>0</code>。</dd> + <dt>{{domxref("HTMLImageElement.referrerPolicy")}} {{experimental_inline}}</dt> + <dd>Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("referrerpolicy", "img")}} HTML attribute indicating which referrer to use in order to fetch the image.</dd> + <dt>{{domxref("HTMLImageElement.src")}}</dt> + <dd>Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("src", "img")}} HTML attribute, containing the full URL of the image including base URI.</dd> + <dt>{{domxref("HTMLImageElement.sizes")}} {{experimental_inline}}</dt> + <dd>Is a {{domxref("DOMString")}} reflecting the {{htmlattrxref("sizes", "img")}} HTML attribute.</dd> + <dt>{{domxref("HTMLImageElement.srcset")}} {{experimental_inline}}</dt> + <dd>Is a {{domxref("DOMString")}} reflecting the {{htmlattrxref("srcset", "img")}} HTML attribute, containing a list of candidate images, separated by a comma (<code>',', U+002C COMMA</code>). A candidate image is a URL followed by a <code>'w'</code> with the width of the images, or an <code>'x'</code> followed by the pixel density.</dd> + <dt>{{domxref("HTMLImageElement.useMap")}}</dt> + <dd>Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("usemap", "img")}} HTML attribute, containing a partial URL of a map element.</dd> + <dt>{{domxref("HTMLImageElement.vspace")}} {{obsolete_inline}}</dt> + <dd>Is a <code>long</code> representing the space above and below the image.</dd> + <dt>{{domxref("HTMLImageElement.width")}}</dt> + <dd>一個反映了 HTML <code>img</code> 元素之 {{htmlattrxref("width", "img")}} 屬性的無符號（<code>unsigned</code>）整數，表示圖片經渲染後的寬度（CSS pixels）。</dd> + <dt>{{domxref("HTMLImageElement.x")}} {{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns a <code>long</code> representing the horizontal offset from the nearest layer. This property mimics an old Netscape 4 behavior.</dd> + <dt>{{domxref("HTMLImageElement.y")}} {{readonlyInline}} {{experimental_inline}}</dt> + <dd>Returns a <code>long</code> representing the vertical offset from the nearest layer. This property is also similar to behavior of an old Netscape 4.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>Inherits properties from its parent, {{domxref("HTMLElement")}}.</em></p> + +<dl> + <dt>{{domxref("HTMLImageElement.Image()", "Image()")}}</dt> + <dd>The <code>Image()</code> constructor, taking two optional <code>unsigned</code> <code>long</code>, which are the width and the height of the resource, creates an instance of <code>HTMLImageElement</code> , not inserted in a DOM tree.</dd> +</dl> + +<h2 id="Errors">Errors</h2> + +<p>If an error occurs while trying to load or render the image, and an {{htmlattrxref("onerror")}} event handler has been configured to handle the {{event("error")}} event, that event handler will get called. This can happen in a number of situations, including:</p> + +<ul> + <li>The {{htmlattrxref("src", "img")}} attribute is empty or <code>null</code>.</li> + <li>The specified <code>src</code> URL is the same as the URL of the page the user is currently on.</li> + <li>The specified image is corrupted in some way that prevents it from being loaded.</li> + <li>The specified image's metadata is corrupted in such a way that it's impossible to retrieve its dimensions, and no dimensions were specified in the <code><img></code> element's attributes.</li> + <li>The specified image is in a format not supported by the {{Glossary("user agent")}}.</li> +</ul> + +<h2 id="範例">範例</h2> + +<pre class="brush: js">var img1 = new Image(); // HTML5 Constructor +img1.src = 'image1.png'; +img1.alt = 'alt'; +document.body.appendChild(img1); + +var img2 = document.createElement('img'); // use DOM <a href="http://mxr.mozilla.org/mozilla-central/source/dom/interfaces/html/nsIDOMHTMLImageElement.idl">HTMLImageElement</a> +img2.src = 'image2.jpg'; +img2.alt = 'alt text'; +document.body.appendChild(img2); + +// using first image in the document +alert(document.images[0].src); +</pre> + +<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('Referrer Policy', '#referrer-policy-delivery-referrer-attribute', 'referrer attribute')}}</td> + <td>{{Spec2('Referrer Policy')}}</td> + <td>Added the <code>referrerPolicy</code> property.</td> + </tr> + <tr> + <td>{{SpecName("CSSOM View", "#excensions-to-the-htmlimageelement-interface", "Extensions to HTMLImageElement")}}</td> + <td>{{Spec2('CSSOM View')}}</td> + <td>Added the <code>x</code> and <code>y</code> properties.</td> + </tr> + <tr> + <td>{{SpecName('HTML WHATWG', "embedded-content.html#the-img-element", "HTMLImageElement")}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>The following properties have been added: <code>srcset</code>, <code>currentSrc</code> and <code>sizes</code>.</td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', "embedded-content-0.html#the-img-element", "HTMLImageElement")}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>A constructor (with 2 optional parameters) has been added.<br> + The following properties are now obsolete: <code>name</code>, <code>border</code>, <code>align</code>, <code>hspace</code>, <code>vspace</code>, and <code>longdesc</code>.<br> + The following properties are now <code>unsigned long</code>, instead of <code>long</code>: <code>height</code>, and <code>width</code>.<br> + The following properties have been added: <code>crossorigin</code>, <code>naturalWidth</code>, <code>naturalHeight</code>, and <code>complete</code>.</td> + </tr> + <tr> + <td>{{SpecName('DOM2 HTML', 'html.html#ID-17701901', 'HTMLImgElement')}}</td> + <td>{{Spec2('DOM2 HTML')}}</td> + <td>The <code>lowSrc</code> property has been removed.<br> + The following properties are now <code>long</code>, instead of <code>DOMString</code>: <code>height</code>, <code>width</code>, <code>hspace</code>, and <code>vspace</code>.</td> + </tr> + <tr> + <td>{{SpecName('DOM1', 'level-one-html.html#ID-17701901', 'HTMLImgElement')}}</td> + <td>{{Spec2('DOM1')}}</td> + <td>Initial definition.</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(1.0)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>lowSrc</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>naturalWidth</code>, <code>naturalHeight</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>9</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>crossorigin</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>9</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>complete</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>5<sup>[4]</sup></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>srcset</code> {{experimental_inline}}</td> + <td>{{CompatChrome(34)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(32)}}<sup>[2]</sup></td> + <td>{{CompatNo}}</td> + <td>21</td> + <td>{{CompatSafari(7.1)}}</td> + </tr> + <tr> + <td><code>currentSrc </code>{{experimental_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(32)}}<sup>[2]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>sizes</code> {{experimental_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(33)}}<sup>[3]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>x</code> and <code>y</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>14<sup>[1]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>referrerPolicy</code> {{experimental_inline}}</td> + <td>{{CompatChrome(51)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop(50)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>onerror</code> event handler</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoDesktop(51)}}<sup>[5]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android Webview</th> + <th>Chrome for Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile(1.0)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>lowSrc</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>naturalWidth</code>, <code>naturalHeight</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>9</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>crossorigin</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>complete</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>srcset</code> {{experimental_inline}}</td> + <td>{{CompatChrome(34)}}</td> + <td>{{CompatChrome(34)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile(32)}}<sup>[2]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>iOS 8</td> + </tr> + <tr> + <td><code>currentSrc </code>{{experimental_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile(32)}}<sup>[2]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>sizes</code> {{experimental_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile(33)}}<sup>[3]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>x</code> and <code>y</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>14<sup>[1]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>referrerPolicy</code> {{experimental_inline}}</td> + <td>{{CompatChrome(51)}}</td> + <td>{{CompatChrome(51)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile(50)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>onerror</code> event handler</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile(51)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Though, these <code>x</code> and <code>y</code> properties were removed in Gecko 7.0 {{geckoRelease("7.0")}} but later, they were restored in Gecko 14.0 {{geckoRelease("14.0")}} for compatibility reasons.</p> + +<p>[2] This feature is behind the <code>dom.image.srcset.enabled</code> preference, defaulting to <code>false</code>.</p> + +<p>[3] This feature is behind the <code>dom.image.picture.enabled</code> preference, defaulting to <code>false</code>.</p> + +<p>[4] IE reports <code>false</code> for broken images.</p> + +<p>[5] May also be supported in earlier versions.</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li>The HTML element implementing this interface: {{HTMLElement("img")}}</li> +</ul> diff --git a/files/zh-tw/web/api/htmlinputelement/index.html b/files/zh-tw/web/api/htmlinputelement/index.html new file mode 100644 index 0000000000..f2b9c9c6ef --- /dev/null +++ b/files/zh-tw/web/api/htmlinputelement/index.html @@ -0,0 +1,592 @@ +--- +title: HTMLInputElement +slug: Web/API/HTMLInputElement +translation_of: Web/API/HTMLInputElement +--- +<div>{{ APIRef("HTML DOM") }}</div> + +<p><strong><code>HTMLInputElement</code></strong> 介面提供了特殊的屬性及方法以操作 <code>input</code> 元素的顯示與佈局。</p> + +<p>{{InheritanceDiagram(600,120)}}</p> + +<h2 id="Properties" name="Properties">屬性</h2> + +<table class="standard-table"> + <caption>Properties related to the parent form</caption> + <thead> + </thead> + <tbody> + <tr> + <td><code>form </code>{{readonlyInline}}</td> + <td><em><code>{{domxref("HTMLFormElement")}} object:</code></em> Returns a reference to the parent form element.</td> + </tr> + <tr> + <td><code>formAction</code></td> + <td><em><code>string</code>: </em>Returns / Sets the element's {{ htmlattrxref("formaction", "input") }} attribute, containing the URI of a program that processes information submitted by the element. This overrides the {{ htmlattrxref("action", "form") }} attribute of the parent form.</td> + </tr> + <tr> + <td><code>formEncType</code></td> + <td><em><code>string</code>:</em> Returns / Sets the element's {{ htmlattrxref("formenctype", "input") }} attribute, containing the type of content that is used to submit the form to the server. This overrides the {{ htmlattrxref("enctype", "form") }} attribute of the parent form.</td> + </tr> + <tr> + <td><code>formMethod</code></td> + <td><em><code>string</code>:</em> Returns / Sets the element's {{ htmlattrxref("formmethod", "input") }} attribute, containing the HTTP method that the browser uses to submit the form. This overrides the {{ htmlattrxref("method", "form") }} attribute of the parent form.</td> + </tr> + <tr> + <td><code>formNoValidate</code></td> + <td><em><code>boolean</code>:</em> Returns / Sets the element's {{ htmlattrxref("formnovalidate", "input") }} attribute, indicating that the form is not to be validated when it is submitted. This overrides the {{ htmlattrxref("novalidate", "form") }} attribute of the parent form.</td> + </tr> + <tr> + <td><code>formTarget</code></td> + <td><em><code>string</code>:</em> Returns / Sets the element's {{ htmlattrxref("formtarget", "input") }} attribute, containing a name or keyword indicating where to display the response that is received after submitting the form. This overrides the {{ htmlattrxref("target", "form") }} attribute of the parent form.</td> + </tr> + </tbody> +</table> + +<table class="standard-table"> + <caption>Properties that apply to any type of input element that is not hidden</caption> + <tbody> + <tr> + <td><code>name</code></td> + <td><em><code>string</code>:</em> Returns / Sets the element's {{ htmlattrxref("name", "input") }} attribute, containing a name that identifies the element when submitting the form.</td> + </tr> + <tr> + <td><code>type</code></td> + <td><code><em>string:</em></code> Returns / Sets the element's {{ htmlattrxref("type", "input") }} attribute, indicating the type of control to display. See {{ htmlattrxref("type", "input") }} attribute of {{ HTMLElement("input") }} for possible values.</td> + </tr> + <tr> + <td><code>disabled</code></td> + <td><em><code>boolean</code>:</em> Returns / Sets the element's {{ htmlattrxref("disabled", "input") }} attribute, indicating that the control is not available for interaction. The input values will not be submitted with the form. See also {{ htmlattrxref("readOnly", "input") }} </td> + </tr> + <tr> + <td><code>autofocus</code></td> + <td><code><em>boolean:</em></code> Returns / Sets the element's {{ htmlattrxref("autofocus", "input") }} attribute, which specifies that a form control should have input focus when the page loads, unless the user overrides it, for example by typing in a different control. Only one form element in a document can have the {{htmlattrxref("autofocus","input")}} attribute. It cannot be applied if the {{htmlattrxref("type","input")}} attribute is set to <code>hidden</code> (that is, you cannot automatically set focus to a hidden control).</td> + </tr> + <tr> + <td><code>required</code></td> + <td><em><code>boolean</code>:</em> Returns / Sets the element's {{ htmlattrxref("required", "input") }} attribute, indicating that the user must fill in a value before submitting a form.</td> + </tr> + <tr> + <td><code>value</code></td> + <td><code><em>string:</em></code> Returns / Sets the current value of the control. + <p class="note"><strong>Note:</strong> If the user enters a value different from the value expected, this may return an empty string.</p> + </td> + </tr> + <tr> + <td><code>validity</code> {{readonlyInline}}</td> + <td><code><em>{{domxref("ValidityState")}} object:</em></code> Returns the validity state that this element is in.</td> + </tr> + <tr> + <td><code>validationMessage</code> {{readonlyInline}}</td> + <td><code><em>string:</em></code> Returns a localized message that describes the validation constraints that the control does not satisfy (if any). This is the empty string if the control is not a candidate for constraint validation ({{htmlattrxref("willValidate","input")}} is false), or it satisfies its constraints.</td> + </tr> + <tr> + <td><code>willValidate </code>{{readonlyInline}}</td> + <td><em><code>{{jsxref("Boolean")}}:</code></em> Indicates whether the element is a candidate for constraint validation. It is false if any conditions bar it from constraint validation.</td> + </tr> + </tbody> +</table> + +<table class="standard-table"> + <caption>Properties that apply only to elements of type "checkbox" or "radio"</caption> + <tbody> + <tr> + <td><code>checked</code></td> + <td> <code><em>boolean:</em> </code>Returns / Sets the current state of the element when {{htmlattrxref("type","input")}} is <code>checkbox</code> or <code>radio</code>.</td> + </tr> + <tr> + <td><code>defaultChecked</code></td> + <td><em><code>boolean:</code></em> Returns / Sets the default state of a radio button or checkbox as originally specified in HTML that created this object.</td> + </tr> + <tr> + <td><code>indeterminate</code></td> + <td><code><em>boolean:</em></code> indicates that the checkbox is neither on nor off.</td> + </tr> + </tbody> +</table> + +<table class="standard-table"> + <caption>Properties that apply only to elements of type "image"</caption> + <tbody> + <tr> + <td><code>alt</code></td> + <td><em><code>string</code>: </em>Returns / Sets the element's {{ htmlattrxref("alt", "input") }} attribute, containing alternative text to use when {{htmlattrxref("type","input")}} is <code>image.</code></td> + </tr> + <tr> + <td><code>height</code></td> + <td><em><code>string</code>: </em>Returns / Sets the element's {{ htmlattrxref("height", "input") }} attribute, which defines the height of the image displayed for the button, if the value of {{htmlattrxref("type","input")}} is <code>image</code>.</td> + </tr> + <tr> + <td><code>src</code></td> + <td><code><em>string:</em></code> Returns / Sets the element's {{ htmlattrxref("src", "input") }} attribute, which specifies a URI for the location of an image to display on the graphical submit button, if the value of {{htmlattrxref("type","input")}} is <code>image</code>; otherwise it is ignored.</td> + </tr> + <tr> + <td><code>width</code></td> + <td><code><em>string:</em></code> Returns / Sets the document's {{ htmlattrxref("width", "input") }} attribute, which defines the width of the image displayed for the button, if the value of {{htmlattrxref("type","input")}} is <code>image</code>.</td> + </tr> + </tbody> +</table> + +<table class="standard-table"> + <caption>Properties that apply only to elements of type "file"</caption> + <tbody> + <tr> + <td><code>accept</code></td> + <td><em><code>string</code>: </em>Returns / Sets the element's {{ htmlattrxref("accept", "input") }} attribute, containing comma-separated list of file types accepted by the server when {{htmlattrxref("type","input")}} is <code>file</code>.</td> + </tr> + <tr> + <td><code>allowdirs</code> {{non-standard_inline}}</td> + <td>boolean: Part of the non-standard Directory Upload API; indicates whether or not to allow directories and files both to be selected in the file list. Implemented only in Firefox and is hidden behind a preference.</td> + </tr> + <tr> + <td>{{domxref("HTMLInputElement.webkitdirectory", "webkitdirectory")}} {{Non-standard_inline}}</td> + <td>boolean: Returns the {{htmlattrxref("webkitdirectory", "input")}} attribute; if true, the file system picker interface only accepts directories instead of files.</td> + </tr> + <tr> + <td>{{domxref("HTMLInputElement.webkitEntries", "webkitEntries")}} {{Non-standard_inline}}</td> + <td>Array of {{domxref("FileSystemEntry")}} objects describing the currently-selected files or directories.</td> + </tr> + </tbody> +</table> + +<table class="standard-table"> + <caption>Properties that apply only to text/number-containing or elements</caption> + <tbody> + <tr> + <td><code>autocomplete</code></td> + <td><em><code>string</code>: </em>Returns / Sets the element's {{htmlattrxref("autocomplete", "input")}} attribute, indicating whether the value of the control can be automatically completed by the browser. Ignored if the value of the {{htmlattrxref("type","input")}} attribute is <code>hidden</code>, <code>checkbox</code>, <code>radio</code>, <code>file</code>, or a button type (<code>button</code>, <code>submit</code>, <code>reset</code>, <code>image</code>). Possible values are:<br> + "on": the browser can autocomplete the value using previously stored value<br> + "off": the user must explicity enter a value</td> + </tr> + <tr> + <td><code>maxLength</code></td> + <td><em><code>long</code>:</em> Returns / Sets the element's {{ htmlattrxref("maxlength", "input") }} attribute, containing the <u><strong>maximum <strong>l</strong>ength of characters</strong></u> (in Unicode code points) that the value can have. (If you set this to a negative number, an exception will be thrown.)</td> + </tr> + <tr> + <td><code>size</code></td> + <td><em><code>unsigned long</code>:</em> Returns / Sets the element's {{ htmlattrxref("size", "input") }} attribute, containing <u><strong>size of the control</strong></u>. This value is in pixels unless the value of {{htmlattrxref("type","input")}} is <code>text</code> or <code>password</code>, in which case, it is an integer number of characters. Applies only when {{htmlattrxref("type","input")}} is set to <code>text</code>, <code>search</code>, <code>tel</code>, <code>url</code>, <code>email</code>, or <code>password</code>; otherwise it is ignored.</td> + </tr> + <tr> + <td><code>pattern</code></td> + <td><em><code>string</code>:</em> Returns / Sets the element's {{ htmlattrxref("pattern", "input") }} attribute, containing a <u><strong>regular expression</strong></u> that the control's value is checked against. Use the {{htmlattrxref("title","input")}} attribute to describe the pattern to help the user. This attribute applies when the value of the {{htmlattrxref("type","input")}} attribute is <code>text</code>, <code>search</code>, <code>tel</code>, <code>url</code> or <code>email</code>; otherwise it is ignored.</td> + </tr> + <tr> + <td><code>placeholder</code></td> + <td><em><code>string</code>: </em>Returns / Sets the element's {{ htmlattrxref("placeholder", "input") }} attribute, containing a hint to the user of what can be entered in the control. The placeholder text must not contain carriage returns or line-feeds. This attribute applies when the value of the {{htmlattrxref("type","input")}} attribute is <code>text</code>, <code>search</code>, <code>tel</code>, <code>url</code> or <code>email</code>; otherwise it is ignored.</td> + </tr> + <tr> + <td><code>readOnly</code></td> + <td><em><code>boolean</code>:</em> Returns / Sets the element's {{ htmlattrxref("readonly", "input") }} attribute, indicating that the user cannot modify the value of the control.<br> + {{HTMLVersionInline(5)}}This is ignored if the value of the {{htmlattrxref("type","input")}} attribute is <code>hidden</code>, <code>range</code>, <code>color</code>, <code>checkbox</code>, <code>radio</code>, <code>file</code>, or a button type.</td> + </tr> + <tr> + <td><code>min</code></td> + <td><em><code>string</code>:</em> Returns / Sets the element's {{ htmlattrxref("min", "input") }} attribute, containing the minimum (numeric or date-time) value for this item, which must not be greater than its maximum ({{htmlattrxref("max","input")}} attribute) value.</td> + </tr> + <tr> + <td><code>max</code></td> + <td><em><code>string</code>:</em> Returns / Sets the element's {{ htmlattrxref("max", "input") }} attribute, containing the maximum (numeric or date-time) value for this item, which must not be less than its minimum (<strong>min</strong> attribute) value.</td> + </tr> + <tr> + <td><code>selectionStart</code></td> + <td><em><code>unsigned long</code>:</em> Returns / Sets the beginning index of the selected text. When nothing is selected, this returns the position of the text input cursor (caret) inside of the {{HTMLElement("input")}} element.</td> + </tr> + <tr> + <td><code>selectionEnd</code></td> + <td><em><code>unsigned long</code>:</em> Returns / Sets the end index of the selected text. When there's no selection, this returns the offset of the character immediately following the current text input cursor position.</td> + </tr> + <tr> + <td><code>selectionDirection</code></td> + <td><em><code>string</code>:</em> Returns / Sets the direction in which selection occurred. Possible values are:<br> + <code>"forward"</code> if selection was performed in the start-to-end direction of the current locale,<br> + <code>"backward"</code> for the opposite direction,<br> + <code>"none"</code> if the direction is unknown."</td> + </tr> + </tbody> +</table> + +<table class="standard-table"> + <caption>Properties not yet categorized</caption> + <tbody> + <tr> + <td><code>defaultValue</code></td> + <td><em><code>string:</code></em> Returns / Sets the default value as originally specified in the HTML that created this object.</td> + </tr> + <tr> + <td><code>dirName</code></td> + <td><em><code>string:</code></em> Returns / Sets the directionality of the element.</td> + </tr> + <tr> + <td><code>accessKey</code></td> + <td><em><code>string</code>: </em>Returns a string containing a single character that switches input focus to the control when pressed.</td> + </tr> + <tr> + <td><code>list</code> {{readonlyInline}}</td> + <td><em><code>{{domxref("HTMLElement")}} object:</code></em> Returns the element pointed by the {{ htmlattrxref("list", "input") }} attribute. The property may be <code>null</code> if no HTML element found in the same tree.</td> + </tr> + <tr> + <td><code>multiple</code></td> + <td><em><code>boolean</code>:</em> Returns / Sets the element's {{ htmlattrxref("multiple", "input") }} attribute, indicating whether more than one value is possible (e.g., multiple files).</td> + </tr> + <tr> + <td><code>files</code> {{readonlyInline}}</td> + <td><em><code>{{domxref("FileList")}} array:</code></em> Returns the list of selected files.</td> + </tr> + <tr> + <td><code>labels</code> {{readonlyInline}}</td> + <td><code><em>{{domxref("NodeList")}} array:</em></code> Returns a list of {{ HTMLElement("label") }} elements that are labels for this element.</td> + </tr> + <tr> + <td><code>step</code></td> + <td><code><em>string:</em></code> Returns / Sets the element's {{ htmlattrxref("step", "input") }} attribute, which works with<strong> </strong>{{htmlattrxref("min","input")}} and {{htmlattrxref("max","input")}} to limit the increments at which a numeric or date-time value can be set. It can be the string <code>any</code> or a positive floating point number. If this is not set to <code>any</code>, the control accepts only values at multiples of the step value greater than the minimum.</td> + </tr> + <tr> + <td><code>valueAsDate</code></td> + <td><code><em>{{jsxref("Date")}} object:</em></code> Returns / Sets the value of the element, interpreted as a date, or <code>null</code> if conversion is not possible.</td> + </tr> + <tr> + <td><code>valueAsNumber</code></td> + <td><code>double</code>: Returns the value of the element, interpreted as one of the following, in order: + <ul> + <li>a time value</li> + <li>a number</li> + <li>NaN if conversion is impossible</li> + </ul> + </td> + </tr> + <tr> + <td><code>autocapitalize</code> {{experimental_inline}}</td> + <td><code><em>string:</em></code> defines the capitalization behavior for user input. Valid values are <code>none</code>, <code>off</code>, <code>characters</code>, <code>words</code>, or <code>sentences</code>.</td> + </tr> + </tbody> +</table> + +<dl> + <dt>{{domxref("HTMLInputElement.align")}} {{obsolete_inline}}</dt> + <dd><code><em>string:</em></code> represents the alignment of the element. <em>Use CSS instead.</em></dd> + <dt>{{domxref("HTMLInputElement.useMap")}} {{ obsolete_inline }}</dt> + <dd><code><em>string:</em></code> represents a client-side image map.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td><code>focus()</code></td> + <td>Focus on the input element; keystrokes will subsequently go to this element.</td> + </tr> + <tr> + <td><code>blur()</code></td> + <td>Removes focus from input; keystrokes will subsequently go nowhere.</td> + </tr> + <tr> + <td><code><a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/select">select()</a></code></td> + <td>Selects the input text in the element, and focuses it so the user can subsequently replace the whole entry.</td> + </tr> + <tr> + <td><code><a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/click">click()</a></code></td> + <td>Simulates a click on the element.</td> + </tr> + <tr> + <td><code><a href="/en-US/docs/Web/API/HTMLInputElement/setSelectionRange">setSelectionRange()</a></code></td> + <td>Selects a range of text in the element (but does not focus it). The optional selectionDirection parameter may be "forward" or "backward" to establish the direction in which selection was set, or "none" if the direction is unknown or not relevant. The default is "none". Specifying a selectionDirection parameter sets the value of the selectionDirection property.</td> + </tr> + <tr> + <td><code>setRangeText()</code></td> + <td>Selects a range of text in the element (but does not focus it). The optional selectionDirection parameter may be "forward" or "backward" to establish the direction in which selection was set, or "none" if the direction is unknown or not relevant. The default is "none". Specifying a selectionDirection parameter sets the value of the selectionDirection property.</td> + </tr> + <tr> + <td><code>setCustomValidity()</code></td> + <td>Sets a custom validity message for the element. If this message is not the empty string, then the element is suffering from a custom validity error, and does not validate.</td> + </tr> + <tr> + <td><code>checkValidity()</code></td> + <td>Returns a {{jsxref("Boolean")}} that is <code>false</code> if the element is a candidate for constraint validation, and it does not satisfy its constraints. In this case, it also fires an {{event("invalid")}} event at the element. It returns <code>true</code> if the element is not a candidate for constraint validation, or if it satisfies its constraints.</td> + </tr> + </tbody> +</table> + +<dl> + <dt>{{domxref("HTMLInputElement.stepDown()")}}</dt> + <dd>Decrements the {{htmlattrxref("value","input")}} by ({{htmlattrxref("step","input")}} * n), where n defaults to 1 if not specified. Throws an INVALID_STATE_ERR exception: + <ul> + <li>if the method is not applicable to for the current {{htmlattrxref("type","input")}} value,</li> + <li>if the element has no {{htmlattrxref("step","input")}} value,</li> + <li>if the {{htmlattrxref("value","input")}} cannot be converted to a number,</li> + <li>if the resulting value is above the {{htmlattrxref("max","input")}} or below the {{htmlattrxref("min","input")}}. </li> + </ul> + </dd> + <dt>{{domxref("HTMLInputElement.stepUp()")}}</dt> + <dd>Increments the {{htmlattrxref("value","input")}} by ({{htmlattrxref("step","input")}} * n), where n defaults to 1 if not specified. Throws an INVALID_STATE_ERR exception: + <ul> + <li>if the method is not applicable to for the current {{htmlattrxref("type","input")}} value.,</li> + <li>if the element has no {{htmlattrxref("step","input")}} value,</li> + <li>if the {{htmlattrxref("value","input")}} cannot be converted to a number,</li> + <li>if the resulting value is above the {{htmlattrxref("max","input")}} or below the {{htmlattrxref("min","input")}}.</li> + </ul> + </dd> + <dt>{{domxref("HTMLInputElement.mozSetFileArray()")}}{{non-standard_inline}}</dt> + <dd>Sets the files selected on the input to the given array of {{domxref("File")}} objects. This is an alternative to <code>mozSetFileNameArray()</code> which can be used in frame scripts: a chrome script can <a href="/en-US/docs/Extensions/Using_the_DOM_File_API_in_chrome_code">open files as File objects</a> and send them via <a href="/en-US/Firefox/Multiprocess_Firefox/The_message_manager">message manager</a>.</dd> + <dt>{{domxref("HTMLInputElement.mozGetFileNameArray()")}}</dt> + <dd>Returns an array of all the file names from the input.</dd> + <dt>{{domxref("HTMLInputElement.mozSetFileNameArray()")}}</dt> + <dd>Sets the filenames for the files selected on the input. Not for use in <a href="/en-US/Firefox/Multiprocess_Firefox/Limitations_of_frame_scripts">frame scripts</a>, because it accesses the file system.</dd> + <dd> + <ul> + </ul> + </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('HTML WHATWG', "forms.html#the-input-element", "HTMLInputElement")}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>No change from {{SpecName("HTML5 W3C")}}</td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', "forms.html#the-input-element", "HTMLInputElement")}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>Technically, the tabindex and accesskey properties, as well as the blur(), click(), and focus() methods, are now defined on {{domxref("HTMLElement")}}.<br> + The following properties are now obsolete: align and useMap.<br> + The following properties have been added: autocomplete, autofocus, dirName, files, formAction, formEncType, formMethod, formNoValidate, formTarget, height, indeterminate, labels, list, max, min, multiple, pattern, placeholder, required, selectionDirection, selectionEnd, selectionStart, step, validationMessage, validity, valueAsDate, valueAsNumber, width, and willValidate.<br> + The following methods have been added: checkValidity(), setCustomValidity(), setSelectionRange(), stepUp(), and stepDown().</td> + </tr> + <tr> + <td>{{SpecName('DOM2 HTML', 'html.html#ID-6043025', 'HTMLInputElement')}}</td> + <td>{{Spec2('DOM2 HTML')}}</td> + <td>The size property is now an unsigned long. The type property must be entirely given in lowercase characters.</td> + </tr> + <tr> + <td>{{SpecName('DOM1', 'level-one-html.html#ID-6043025', 'HTMLInputElement')}}</td> + <td>{{Spec2('DOM1')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(1.0)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>autocomplete & autofocus properties</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>files property</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(1.9)}}</td> + <td>10</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>multiple property</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1.9.2")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>indeterminate property</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>list property</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>formAction, formEncType, formMethod, formTarget properties</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(2)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>formNoValidate, validationMessage, validity, willValidate properties and setCustomValidity() and checkValidity() methods.</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(2)}}</td> + <td>10</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>pattern, placeholder, required properties</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(2)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>height and weight properties</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(16)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>labels property</td> + <td>{{CompatChrome(14.0)}}</td> + <td>{{CompatNo}} ({{bug("556743")}})</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>min, max, and step for <input type="number"></td> + <td>{{CompatVersionUnknown}}</td> + <td>Experimental, and without specific UI, since {{CompatGeckoDesktop(16)}}: behind the pref dom.experimental_forms</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>stepUp and stepDown methods</td> + <td>{{CompatUnknown}}</td> + <td>Experimental since {{CompatGeckoDesktop(16)}}: behind the pref dom.experimental_forms<br> + <br> + There are still differences with the latest spec: {{bug(835773)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>min, max, and step properties for <input type="range"></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(23)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>min, max, and step properties for <input type="date"></td> + <td>{{CompatVersionUnknown}}</td> + <td>Experimental, and without specific UI, since {{CompatGeckoDesktop(20)}}: behind the pref dom.experimental_forms</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>min, max, and step properties for other date-related type values</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>mozGetFileNameArray() and mozSetFileNameArray() methods {{non-standard_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop("1.9.2")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>mozSetFileArray() method {{non-standard_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop("38")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>autocapitalize</td> + <td>{{CompatChrome(43.0)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</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>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + <th>Chrome for Android</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile(1.0)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>autocapitalize</td> + <td>{{CompatNo}}</td> + <td>{{CompatChrome(43.0)}}</td> + <td>{{CompatUnknown}}</td> + <td><span style="font-size: 12px; line-height: 16.3636360168457px;">{{CompatUnknown}}</span></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatChrome(43.0)}}</td> + </tr> + </tbody> +</table> + +<p> </p> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li>HTML element implementing this interface: {{ HTMLElement("input") }}.</li> +</ul> diff --git a/files/zh-tw/web/api/htmlmediaelement/index.html b/files/zh-tw/web/api/htmlmediaelement/index.html new file mode 100644 index 0000000000..68d1122e81 --- /dev/null +++ b/files/zh-tw/web/api/htmlmediaelement/index.html @@ -0,0 +1,243 @@ +--- +title: HTMLMediaElement +slug: Web/API/HTMLMediaElement +translation_of: Web/API/HTMLMediaElement +--- +<p>{{APIRef("HTML DOM")}}</p> + +<p><span class="seoSummary">The <strong><code>HTMLMediaElement</code></strong> interface adds to {{domxref("HTMLElement")}} the properties and methods needed to support basic media-related capabilities that are common to audio and video.</span> The {{domxref("HTMLVideoElement")}} and {{domxref("HTMLAudioElement")}} elements both inherit this interface.</p> + +<p>{{InheritanceDiagram(600, 120)}}</p> + +<h2 id="屬性">屬性</h2> + +<p><em>這個介面從{{domxref("HTMLElement")}}、{{domxref("Element")}}、{{domxref("Node")}}，和{{domxref("EventTarget")}}繼承了屬性</em></p> + +<dl> + <dt>{{domxref("HTMLMediaElement.audioTracks")}}</dt> + <dd>{{domxref("AudioTrackList")}} 會列出包含在該媒體元素內部的{{domxref("AudioTrack")}}物件。</dd> + <dt>{{domxref("HTMLMediaElement.autoplay")}}</dt> + <dd>是一個布林值，表達了HTML中是否有{{htmlattrxref("autoplay", "video")}}屬性；意即；表明是否只要在媒體可以播放且不中斷的時候，能夠自動播放。 + <div class="note">在網站上自動播放音訊（或是有音訊的影片），可能是惱人的使用者體驗；因此，應該盡可能地避免。如果你必須要有自動播放的功能，你應該讓它是可選擇的（讓使用者特地去啟動）。 However, this can be useful when creating media elements whose source will be set at a later time, under user control.</div> + </dd> + <dt>{{domxref("HTMLMediaElement.buffered")}} {{readonlyinline}}</dt> + <dd>回傳一個{{domxref("TimeRanges")}}物件，表示媒體當下<code>buffered</code>屬性被瀏覽器存取時的緩存（如果有的話）區間。</dd> + <dt>{{domxref("HTMLMediaElement.controller")}}</dt> + <dd>Is a {{domxref("MediaController")}} object that represents the media controller assigned to the element, or <code>null</code> if none is assigned.</dd> + <dt>{{domxref("HTMLMediaElement.controls")}}</dt> + <dd>Is a {{jsxref('Boolean')}} that reflects the {{htmlattrxref("controls", "video")}} HTML attribute, indicating whether user interface items for controlling the resource should be displayed.</dd> + <dt>{{domxref("HTMLMediaElement.controlsList")}} {{readonlyinline}}</dt> + <dd>Returns a {{domxref("DOMTokenList")}} that helps the user agent select what controls to show on the media element whenever the user agent shows its own set of controls. The <code>DOMTokenList</code> takes one or more of three possible values: <code>nodownload</code>, <code>nofullscreen</code>, and <code>noremoteplayback</code>.</dd> + <dt>{{domxref("HTMLMediaElement.crossOrigin")}}</dt> + <dd>Is a {{domxref("DOMString")}} indicating the <a href="/en-US/docs/Web/HTML/CORS_settings_attributes">CORS setting</a> for this media element.</dd> + <dt>{{domxref("HTMLMediaElement.currentSrc")}} {{readonlyinline}}</dt> + <dd>Returns a {{domxref("DOMString")}} with the absolute URL of the chosen media resource.</dd> + <dt>{{domxref("HTMLMediaElement.currentTime")}}</dt> + <dd>Is a <code>double</code> indicating the current playback time in seconds. Setting this value seeks the media to the new time.</dd> + <dt>{{domxref("HTMLMediaElement.defaultMuted")}}</dt> + <dd>Is a {{jsxref('Boolean')}} that reflects the {{htmlattrxref("muted", "video")}} HTML attribute, which indicates whether the media element's audio output should be muted by default.</dd> + <dt>{{domxref("HTMLMediaElement.defaultPlaybackRate")}}</dt> + <dd>Is a <code>double</code> indicating the default playback rate for the media.</dd> + <dt>{{domxref("HTMLMediaElement.disableRemotePlayback")}}</dt> + <dd>Is a {{jsxref('Boolean')}} that sets or returns the remote playback state, indicating whether the media element is allowed to have a remote playback UI.</dd> + <dt>{{domxref("HTMLMediaElement.duration")}} {{readonlyinline}}</dt> + <dd>Returns a <code>double</code> indicating the length of the media in seconds, or 0 if no media data is available.</dd> + <dt>{{domxref("HTMLMediaElement.ended")}} {{readonlyinline}}</dt> + <dd>Returns a {{jsxref('Boolean')}} that indicates whether the media element has finished playing.</dd> + <dt>{{domxref("HTMLMediaElement.error")}} {{readonlyinline}}</dt> + <dd>Returns a {{domxref("MediaError")}} object for the most recent error, or <code>null</code> if there has not been an error.</dd> + <dt>{{domxref("HTMLMediaElement.loop")}}</dt> + <dd>Is a {{jsxref('Boolean')}} that reflects the {{htmlattrxref("loop", "video")}} HTML attribute, which indicates whether the media element should start over when it reaches the end.</dd> + <dt>{{domxref("HTMLMediaElement.mediaGroup")}}</dt> + <dd>Is a {{domxref("DOMString")}} that reflects the {{ htmlattrxref("mediagroup", "video")}} HTML attribute, which indicates the name of the group of elements it belongs to. A group of media elements shares a common {{domxref('MediaController')}}.</dd> + <dt>{{domxref("HTMLMediaElement.mediaKeys")}} {{readonlyinline}} {{experimental_inline}}</dt> + <dd>Returns a {{domxref("MediaKeys")}} object or <code>null</code>. MediaKeys is a set of keys that an associated HTMLMediaElement can use for decryption of media data during playback.</dd> + <dt>{{domxref("HTMLMediaElement.mozAudioCaptured")}} {{readonlyinline}} {{non-standard_inline}}</dt> + <dd>Returns a {{jsxref('Boolean')}}. Related to audio stream capture.</dd> + <dt>{{domxref("HTMLMediaElement.mozFragmentEnd")}} {{non-standard_inline}}</dt> + <dd>Is a <code>double</code> that provides access to the fragment end time if the media element has a fragment URI for <code>currentSrc</code>, otherwise it is equal to the media duration.</dd> + <dt>{{domxref("HTMLMediaElement.mozFrameBufferLength")}} {{non-standard_inline}} {{deprecated_inline}}</dt> + <dd> + <p>Is a <code>unsigned long</code> that indicates the number of samples that will be returned in the framebuffer of each <code>MozAudioAvailable</code> event. This number is a total for all channels, and by default is set to be the number of channels * 1024 (e.g., 2 channels * 1024 samples = 2048 total).</p> + + <p>The <code>mozFrameBufferLength</code> property can be set to a new value for lower latency, larger amounts of data, etc. The size given <em>must</em> be a number between 512 and 16384. Using any other size results in an exception being thrown. The best time to set a new length is after the <a href="/en-US/docs/Web/Events/loadedmetadata">loadedmetadata</a> event fires, when the audio info is known, but before the audio has started or <code>MozAudioAvailable</code> events have begun firing.</p> + </dd> + <dt>{{domxref("HTMLMediaElement.mozSampleRate")}} {{readonlyinline}} {{non-standard_inline}} {{deprecated_inline}}</dt> + <dd>Returns a <code>double</code> representing the number of samples per second that will be played. For example, 44100 samples per second is the sample rate used by CD audio.</dd> + <dt>{{domxref("HTMLMediaElement.muted")}}</dt> + <dd>Is a {{jsxref('Boolean')}} that determines whether audio is muted. <code>true</code> if the audio is muted and <code>false</code> otherwise.</dd> + <dt>{{domxref("HTMLMediaElement.networkState")}} {{readonlyinline}}</dt> + <dd>Returns a <code>unsigned short</code> (enumeration) indicating the current state of fetching the media over the network.</dd> + <dt>{{domxref("HTMLMediaElement.paused")}} {{readonlyinline}}</dt> + <dd>Returns a {{jsxref('Boolean')}} that indicates whether the media element is paused.</dd> + <dt>{{domxref("HTMLMediaElement.playbackRate")}}</dt> + <dd>Is a <code>double</code> that indicates the rate at which the media is being played back. </dd> + <dt>{{domxref("HTMLMediaElement.played")}} {{readonlyinline}}</dt> + <dd>Returns a {{domxref('TimeRanges')}} object that contains the ranges of the media source that the browser has played, if any.</dd> + <dt>{{domxref("HTMLMediaElement.preload")}}</dt> + <dd>Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("preload", "video")}} HTML attribute, indicating what data should be preloaded, if any. Possible values are: <code>none</code>, <code>metadata</code>, <code>auto</code>.</dd> + <dt>{{domxref("HTMLMediaElement.preservesPitch")}} {{non-standard_inline}}</dt> + <dd>Is a {{jsxref('Boolean')}} that determines if the pitch of the sound will be preserved. If set to <code>false</code>, the pitch will adjust to the speed of the audio. This is implemented with prefixes in Firefox (<code>mozPreservesPitch</code>) and WebKit (<code>webkitPreservesPitch</code>).</dd> + <dt>{{domxref("HTMLMediaElement.readyState")}} {{readonlyinline}}</dt> + <dd>Returns a <code>unsigned short</code> (enumeration) indicating the readiness state of the media.</dd> + <dt>{{domxref("HTMLMediaElement.seekable")}} {{readonlyinline}}</dt> + <dd>Returns a {{domxref('TimeRanges')}} object that contains the time ranges that the user is able to seek to, if any.</dd> + <dt>{{domxref("HTMLMediaElement.seeking")}} {{readonlyinline}}</dt> + <dd>Returns a {{jsxref('Boolean')}} that indicates whether the media is in the process of seeking to a new position.</dd> + <dt>{{domxref("HTMLMediaElement.sinkId")}} {{readonlyinline}} {{experimental_inline}}</dt> + <dd>Returns a {{domxref("DOMString")}} that is the unique ID of the audio device delivering output, or an empty string if it is using the user agent default. This ID should be one of the <code>MediaDeviceInfo.deviceid</code> values returned from {{domxref("MediaDevices.enumerateDevices()")}}, <code>id-multimedia</code>, or <code>id-communications</code>.</dd> + <dt>{{domxref("HTMLMediaElement.src")}}</dt> + <dd>Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("src", "video")}} HTML attribute, which contains the URL of a media resource to use.</dd> + <dt>{{domxref("HTMLMediaElement.srcObject")}}</dt> + <dd>Is a {{domxref('MediaStream')}} representing the media to play or that has played in the current <code>HTMLMediaElement</code>, or <code>null</code> if not assigned.</dd> + <dt>{{domxref("HTMLMediaElement.textTracks")}} {{readonlyinline}}</dt> + <dd>Returns the list of {{domxref("TextTrack")}} objects contained in the element.</dd> + <dt>{{domxref("HTMLMediaElement.videoTracks")}} {{readonlyinline}}</dt> + <dd>Returns the list of {{domxref("VideoTrack")}} objects contained in the element. + <div class="note"> + <p>Gecko supports only single track playback, and the parsing of tracks' metadata is only available for media with the Ogg container format.</p> + </div> + </dd> + <dt>{{domxref("HTMLMediaElement.volume")}}</dt> + <dd>Is a <code>double</code> indicating the audio volume, from 0.0 (silent) to 1.0 (loudest).</dd> +</dl> + +<h3 id="Event_handlers">Event handlers</h3> + +<dl> + <dt> </dt> + <dt>{{domxref("HTMLMediaElement.onencrypted")}}</dt> + <dd>Sets the {{domxref('EventHandler')}} called when the media is encrypted.</dd> + <dt>{{domxref("HTMLMediaElement.onwaitingforkey")}}</dt> + <dd>Sets the {{domxref('EventHandler')}} called when playback is blocked while waiting for an encryption key.</dd> +</dl> + +<h2 id="Obsolete_attributes">Obsolete attributes</h2> + +<p>These attributes are obsolete and should not be used, even if a browser still supports them.</p> + +<p> </p> + +<dl> + <dt>{{domxref("HTMLMediaElement.initialTime")}} {{readonlyinline}} {{non-standard_inline}} {{obsolete_inline}}</dt> + <dd>Returns a <code>double</code> that indicates the initial playback position in seconds.</dd> + <dt>{{domxref("HTMLMediaElement.mozChannels")}} {{readonlyinline}} {{non-standard_inline}} {{deprecated_inline}}</dt> + <dd>Returns a <code>double</code> representing the number of channels in the audio resource (e.g., <code>2</code> for stereo).</dd> +</dl> + +<h3 id="Obsolete_event_handlers">Obsolete event handlers</h3> + +<p> </p> + +<dl> + <dt>{{domxref("HTMLMediaElement.onmozinterruptbegin")}} {{non-standard_inline}} {{obsolete_inline}}</dt> + <dd>Sets the {{domxref("EventHandler")}} called when the media element is interrupted because of the Audio Channel manager. This was Firefox-specific, having been implemented for Firefox OS, and was removed in Firefox 55.</dd> + <dt>{{domxref("HTMLMediaElement.onmozinterruptend")}} {{non-standard_inline}} {{obsolete_inline}}</dt> + <dd>Sets the {{domxref('EventHandler')}} called when the interruption is concluded. This was Firefox-specific, having been implemented for Firefox OS, and was removed in Firefox 55.</dd> +</dl> + +<p> </p> + +<p> </p> + +<h2 id="Methods">Methods</h2> + +<p><em>This interface also inherits methods from its ancestors {{domxref("HTMLElement")}}, {{domxref('Element')}}, {{domxref('Node')}}, and {{domxref('EventTarget')}}.</em></p> + +<dl> + <dt>{{domxref("HTMLMediaElement.addTextTrack()")}}</dt> + <dd>Adds a text track (such as a track for subtitles) to a media element.</dd> + <dt>{{domxref("HTMLMediaElement.captureStream()")}} {{experimental_inline}}</dt> + <dd>Returns {{domxref("MediaStream")}}, captures a stream of the media content.</dd> + <dt>{{domxref("HTMLMediaElement.canPlayType()")}}</dt> + <dd>Determines whether the specified media type can be played back.</dd> + <dt>{{domxref("HTMLMediaElement.fastSeek()")}}</dt> + <dd>Directly seeks to the given time.</dd> + <dt>{{domxref("HTMLMediaElement.load()")}}</dt> + <dd>Resets the media element and restarts the media resource. Any pending events are discarded. How much media data is fetched is still affected by the <code>preload</code> attribute. This method can be useful for releasing resources after any <code>src</code> attribute and <code>source</code> element descendants have been removed. Otherwise, it is usually unnecessary to use this method, unless required to rescan <code>source</code> element children after dynamic changes.</dd> + <dt>{{domxref("HTMLMediaElement.mozCaptureStream()")}} {{non-standard_inline}}</dt> + <dd>[enter description]</dd> + <dt>{{domxref("HTMLMediaElement.mozCaptureStreamUntilEnded()")}} {{non-standard_inline}}</dt> + <dd>[enter description]</dd> + <dt>{{domxref("HTMLMediaElement.mozGetMetadata()")}} {{non-standard_inline}}</dt> + <dd>Returns {{jsxref('Object')}}, which contains properties that represent metadata from the playing media resource as <code>{key: value}</code> pairs. A separate copy of the data is returned each time the method is called. This method must be called after the <a href="/en-US/docs/Web/Events/loadedmetadata">loadedmetadata</a> event fires.</dd> + <dt>{{domxref("HTMLMediaElement.pause()")}}</dt> + <dd>Pauses the media playback.</dd> + <dt>{{domxref("HTMLMediaElement.play()")}}</dt> + <dd>Begins playback of the media.</dd> + <dt>{{domxref("HTMLMediaElement.seekToNextFrame()")}} {{non-standard_inline}} {{experimental_inline}}</dt> + <dd>Seeks to the next frame in the media. This non-standard, experimental method makes it possible to manually drive reading and rendering of media at a custom speed, or to move through the media frame-by-frame to perform filtering or other operations.</dd> + <dt>{{domxref("HTMLMediaElement.setMediaKeys()")}} {{experimental_inline}}</dt> + <dd>Returns {{jsxref("Promise")}}. Sets the {{domxref("MediaKeys")}} keys to use when decrypting media during playback.</dd> + <dt>{{domxref("HTMLMediaElement.setSinkId()")}} {{experimental_inline}}</dt> + <dd>Sets the ID of the audio device to use for output and returns a {{jsxref("Promise")}}. This only works when the application is authorized to use the specified device.</dd> +</dl> + +<h2 id="Obsolete_methods">Obsolete methods</h2> + +<p>These methods are obsolete and should not be used, even if a browser still supports them.</p> + +<p> </p> + +<dl> + <dt>{{domxref("HTMLMediaElement.mozLoadFrom()")}} {{non-standard_inline}} {{deprecated_inline}}</dt> + <dd>This method, available only in Mozilla's implementation, loads data from another media element. This works similarly to <code>load()</code> except that instead of running the normal resource selection algorithm, the source is simply set to the <code>other</code> element's <code>currentSrc</code>. This is optimized so this element gets access to all of the <code>other</code> element's cached and buffered data; in fact, the two elements share downloaded data, so data downloaded by either element is available to both.</dd> +</dl> + +<p> </p> + +<h2 id="Specifications">Specifications</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('HTML WHATWG', "the-video-element.html#htmlmediaelement", "HTMLMediaElement")}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>No change from {{SpecName('HTML5 W3C')}}</td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', "embedded-content-0.html#htmlmediaelement", "HTMLMediaElement")}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>Initial definition.</td> + </tr> + <tr> + <td>{{SpecName('EME', '#introduction', 'Encrypted Media Extensions')}}</td> + <td>{{Spec2('EME')}}</td> + <td>Adds {{domxref("MediaKeys")}}, {{domxref("MediaEncryptedEvent")}}, {{domxref("setMediaKeys")}}, {{domxref("onencrypted")}}, and {{domxref("onwaitingforkey")}}.</td> + </tr> + <tr> + <td>{{SpecName('Media Capture','#htmlmediaelement-extensions','HTMLMediaElement')}}</td> + <td>{{Spec2('Media Capture')}}</td> + <td>Adds <code>sinkId</code> and <code>setSinkId()</code>, and <code>captureStream()</code>.</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + + + +<p>{{Compat("api.HTMLMediaElement")}}</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li>References + <ul> + <li>{{HTMLElement("video")}} and {{HTMLElement("audio")}} HTML elements.</li> + <li>{{domxref("HTMLVideoElement")}} and {{domxref("HTMLAudioElement")}} interfaces, derived from <code>HTMLMediaElement</code>.</li> + </ul> + </li> + <li>Articles + <ul> + <li><a class="internal" href="/en-US/docs/Using_HTML5_audio_and_video">Using HTML5 audio and video</a></li> + <li><a class="internal" href="/en-US/docs/Media_formats_supported_by_the_audio_and_video_elements">Media formats supported by the audio and video elements</a></li> + <li><a href="/en-US/docs/Web_Audio_API">Web Audio API</a></li> + </ul> + </li> +</ul> diff --git a/files/zh-tw/web/api/htmlmediaelement/ratechange_event/index.html b/files/zh-tw/web/api/htmlmediaelement/ratechange_event/index.html new file mode 100644 index 0000000000..e4c6a3d743 --- /dev/null +++ b/files/zh-tw/web/api/htmlmediaelement/ratechange_event/index.html @@ -0,0 +1,82 @@ +--- +title: 'HTMLMediaElement: ratechange' +slug: Web/API/HTMLMediaElement/ratechange_event +tags: + - 播放速度 速度 速率 +translation_of: Web/API/HTMLMediaElement/ratechange_event +--- +<p><code>ratechange</code> 事件將在播放速度改變時被觸發</p> + +<h2 id="基本資訊">基本資訊</h2> + +<dl> + <dt style="float: left; text-align: right; width: 120px;">規格</dt> + <dd style="margin: 0 0 0 120px;"><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-video-element.html#event-media-ratechange">HTML5 Media</a></dd> + <dt style="float: left; text-align: right; width: 120px;">介面</dt> + <dd style="margin: 0 0 0 120px;">事件</dd> + <dt style="float: left; text-align: right; width: 120px;">是否冒泡</dt> + <dd style="margin: 0 0 0 120px;">否</dd> + <dt style="float: left; text-align: right; width: 120px;">是否可取消</dt> + <dd style="margin: 0 0 0 120px;">否</dd> + <dt style="float: left; text-align: right; width: 120px;">目標</dt> + <dd style="margin: 0 0 0 120px;">元素</dd> + <dt style="float: left; text-align: right; width: 120px;">預設行為</dt> + <dd style="margin: 0 0 0 120px;">無</dd> +</dl> + +<h2 id="屬性">屬性</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">屬性</th> + <th scope="col">類型</th> + <th scope="col">描述</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>target</code> {{readonlyInline}}</td> + <td>{{domxref("EventTarget")}}</td> + <td>事件目標（DOM樹中最頂層的目標)</td> + </tr> + <tr> + <td><code>type</code> {{readonlyInline}}</td> + <td>{{domxref("DOMString")}}</td> + <td>事件類型</td> + </tr> + <tr> + <td><code>bubbles</code> {{readonlyInline}}</td> + <td>{{jsxref("Boolean")}}</td> + <td>事件是否觸發冒泡</td> + </tr> + <tr> + <td><code>cancelable</code> {{readonlyInline}}</td> + <td>{{jsxref("Boolean")}}</td> + <td>事件是否可取消</td> + </tr> + </tbody> +</table> + +<h2 id="相關事件">相關事件</h2> + +<ul> + <li>{{event("playing")}}</li> + <li>{{event("waiting")}}</li> + <li>{{event("seeking")}}</li> + <li>{{event("seeked")}}</li> + <li>{{event("ended")}}</li> + <li>{{event("loadedmetadata")}}</li> + <li>{{event("loadeddata")}}</li> + <li>{{event("canplay")}}</li> + <li>{{event("canplaythrough")}}</li> + <li>{{event("durationchange")}}</li> + <li>{{event("timeupdate")}}</li> + <li>{{event("play")}}</li> + <li>{{event("pause")}}</li> + <li>{{event("ratechange")}}</li> + <li>{{event("volumechange")}}</li> + <li>{{event("suspend")}}</li> + <li>{{event("emptied")}}</li> + <li>{{event("stalled")}}</li> +</ul> diff --git a/files/zh-tw/web/api/htmlmediaelement/readystate/index.html b/files/zh-tw/web/api/htmlmediaelement/readystate/index.html new file mode 100644 index 0000000000..14df7bb4e0 --- /dev/null +++ b/files/zh-tw/web/api/htmlmediaelement/readystate/index.html @@ -0,0 +1,110 @@ +--- +title: HTMLMediaElement.readyState +slug: Web/API/HTMLMediaElement/readyState +translation_of: Web/API/HTMLMediaElement/readyState +--- +<div>{{APIRef("HTML DOM")}}</div> + +<div><strong><code>HTMLMediaElement.readyState</code> </strong>屬性回傳目前媒體的就緒狀態。</div> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox">var readyState = audioOrVideo.readyState;</pre> + +<h3 id="值">值</h3> + +<p>一個 <code>unsigned short</code>，可能的值有：</p> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">常數</th> + <th scope="col">值</th> + <th scope="col">描述</th> + </tr> + </thead> + <tbody> + <tr> + <td>HAVE_NOTHING</td> + <td>0</td> + <td>沒有可用的媒體資源。</td> + </tr> + <tr> + <td>HAVE_METADATA</td> + <td>1</td> + <td>已經取得足夠的媒體資源並已初始化元資料。繼續取得媒體資源不會導致例外。</td> + </tr> + <tr> + <td>HAVE_CURRENT_DATA</td> + <td>2</td> + <td>媒體資料已經足夠播放目前的時間，但沒有足夠的資料再播放一幀。</td> + </tr> + <tr> + <td>HAVE_FUTURE_DATA</td> + <td>3</td> + <td>資料已經足夠播放目前的時間，而且有至少一點點資料可以播放未來的時間（換句話說，可能只多了一到兩幀）。</td> + </tr> + <tr> + <td>HAVE_ENOUGH_DATA</td> + <td>4</td> + <td>資料足夠，且下載率夠高。媒體可以播放到結束而不被中斷。</td> + </tr> + </tbody> +</table> + +<h2 id="範例">範例</h2> + +<p>下面這個例子會監聽 `example` 這個元素，並檢查是否已載入足夠的媒體資源。如果是的話，它會繼續播放。</p> + +<pre class="brush: html"><audio id="example" preload="auto"> + <source src="sound.ogg" type="audio/ogg" /> +</audio> + +</pre> + +<pre class="brush: js">var obj = document.getElementById('example'); + +obj.addEventListener('loadeddata', function() { + + if(obj.readyState >= 2) { + obj.play(); + } + +}); +</pre> + +<p> </p> + +<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('HTML WHATWG', "the-video-element.html#htmlmediaelement", "HTMLMediaElement.readyState")}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>No change from {{SpecName('HTML5 W3C')}}</td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', "embedded-content-0.html#htmlmediaelement", "HTMLMediaElement.readyState")}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + + + +<p>{{Compat("api.HTMLMediaElement.readyState")}}</p> + +<h2 id="See_Also" name="See_Also">也參考看看</h2> + +<ul> + <li>The interface defining it, {{domxref("HTMLMediaElement")}}.</li> +</ul> diff --git a/files/zh-tw/web/api/htmlselectelement/checkvalidity/index.html b/files/zh-tw/web/api/htmlselectelement/checkvalidity/index.html new file mode 100644 index 0000000000..8ded860ac4 --- /dev/null +++ b/files/zh-tw/web/api/htmlselectelement/checkvalidity/index.html @@ -0,0 +1,98 @@ +--- +title: HTMLSelectElement.checkValidity() +slug: Web/API/HTMLSelectElement/checkValidity +translation_of: Web/API/HTMLSelectElement/checkValidity +--- +<div>{{ APIRef("HTML DOM") }}</div> + +<p><code><strong>HTMLSelectElement.checkValidity()</strong></code> 方法會檢查元素是否有任何的檢核、驗證條件，並且檢查是否滿足這些條件。如果元素沒有通過這些檢核，瀏覽器會於該元素上觸發一個可取消的 {{event("invalid")}} 事件，並回傳 <code>false</code>。</p> + +<h2 id="語法">語法</h2> + +<pre class="eval language-html"><code class="language-html">var <em>result</em> = <em>selectElt</em>.checkValidity();</code></pre> + +<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('HTML WHATWG', '#dom-cva-checkvalidity', 'HTMLSelectElement.checkValidity()')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>No change since the latest snapshot, {{SpecName('HTML5 W3C')}}.</td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', 'forms.html#dom-cva-checkvalidity', 'HTMLSelectElement.checkValidity()')}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>Initial definition, snapshot of {{SpecName('HTML WHATWG')}}</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(2.0)}}</td> + <td>10</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile(2.0)}}</td> + <td>1.0</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation">Form validation.</a></li> +</ul> diff --git a/files/zh-tw/web/api/htmlselectelement/index.html b/files/zh-tw/web/api/htmlselectelement/index.html new file mode 100644 index 0000000000..0110568dd6 --- /dev/null +++ b/files/zh-tw/web/api/htmlselectelement/index.html @@ -0,0 +1,283 @@ +--- +title: HTMLSelectElement +slug: Web/API/HTMLSelectElement +translation_of: Web/API/HTMLSelectElement +--- +<div>{{APIRef("HTML DOM")}}</div> + +<p><code><strong>HTMLSelectElement</strong></code> 介面代表了 {{HTMLElement("select")}} HTML 元素。此介面也自 {{domxref("HTMLElement")}} 介面繼承了所有 HTML 元素的屬性及方法。</p> + +<p>{{InheritanceDiagram(600, 120)}}</p> + +<h2 id="屬性">屬性</h2> + +<p><em>This interface inherits the properties of {{domxref("HTMLElement")}}, and of {{domxref("Element")}} and {{domxref("Node")}}.</em></p> + +<dl> + <dt>{{domxref("HTMLSelectElement.autofocus")}}</dt> + <dd>A {{jsxref("Boolean")}} reflecting the {{htmlattrxref("autofocus", "select")}} HTML attribute, which indicates whether the control should have input focus when the page loads, unless the user overrides it, for example by typing in a different control. Only one form-associated element in a document can have this attribute specified. {{gecko_minversion_inline("2.0")}}</dd> + <dt>{{domxref("HTMLSelectElement.disabled")}}</dt> + <dd>A {{jsxref("Boolean")}} reflecting the {{htmlattrxref("disabled", "select")}} HTML attribute, which indicates whether the control is disabled. If it is disabled, it does not accept clicks.</dd> + <dt>{{domxref("HTMLSelectElement.form")}}{{ReadOnlyInline}}</dt> + <dd>An {{domxref("HTMLFormElement")}} referencing the form that this element is associated with. If the element is not associated with of a {{HTMLElement("form")}} element, then it returns <code>null</code>.</dd> + <dt>{{domxref("HTMLSelectElement.labels")}}{{ReadOnlyInline}}</dt> + <dd>A {{domxref("NodeList")}} of {{HTMLElement("label")}} elements associated with the element.</dd> + <dt>{{domxref("HTMLSelectElement.length")}}</dt> + <dd>An <code>unsigned long </code>The number of {{HTMLElement("option")}} elements in this <code>select</code> element.</dd> + <dt>{{domxref("HTMLSelectElement.multiple")}}</dt> + <dd>A {{jsxref("Boolean")}} reflecting the {{htmlattrxref("multiple", "select")}} HTML attribute, which indicates whether multiple items can be selected.</dd> + <dt>{{domxref("HTMLSelectElement.name")}}</dt> + <dd>A {{domxref("DOMString")}} reflecting the {{htmlattrxref("name", "select")}} HTML attribute, containing the name of this control used by servers and DOM search functions.</dd> + <dt>{{domxref("HTMLSelectElement.options")}}{{ReadOnlyInline}}</dt> + <dd>An {{domxref("HTMLOptionsCollection")}} representing the set of {{HTMLElement("option")}} elements contained by this element.</dd> + <dt>{{domxref("HTMLSelectElement.required")}}</dt> + <dd>A {{jsxref("Boolean")}} reflecting the {{htmlattrxref("required", "select")}} HTML attribute, which indicates whether the user is required to select a value before submitting the form. {{gecko_minversion_inline("2.0")}}</dd> + <dt>{{domxref("HTMLSelectElement.selectedIndex")}}</dt> + <dd>A <code>long</code> reflecting the index of the first selected {{HTMLElement("option")}} element. The value <code>-1</code> indicates no element is selected.</dd> + <dt>{{domxref("HTMLSelectElement.selectedOptions")}}{{ReadOnlyInline}}</dt> + <dd>An {{domxref("HTMLCollection")}} representing the set of {{HTMLElement("option")}} elements that are selected.</dd> + <dt>{{domxref("HTMLSelectElement.size")}}</dt> + <dd>A <code>long</code> reflecting the {{htmlattrxref("size", "select")}} HTML attribute, which contains the number of visible items in the control. The default is 1, unless <code>multiple</code> is true, in which case it is 4.</dd> + <dt>{{domxref("HTMLSelectElement.type")}}{{ReadOnlyInline}}</dt> + <dd>A {{domxref("DOMString")}} represeting the form control's type. When <code>multiple</code> is <code>true</code>, it returns <code>"select-multiple"</code>; otherwise, it returns <code>"select-one"</code>.</dd> + <dt>{{domxref("HTMLSelectElement.validationMessage")}}{{ReadOnlyInline}}</dt> + <dd>A {{domxref("DOMString")}} representing a localized message that describes the validation constraints that the control does not satisfy (if any). This attribute is the empty string if the control is not a candidate for constraint validation (<code>willValidate</code> is false), or it satisfies its constraints.</dd> + <dt>{{domxref("HTMLSelectElement.validity")}}{{ReadOnlyInline}}</dt> + <dd>A {{domxref("ValidityState")}} reflecting the validity state that this control is in.</dd> + <dt>{{domxref("HTMLSelectElement.value")}}</dt> + <dd>A {{domxref("DOMString")}} reflecting the value of the form control (the first selected option).</dd> + <dt>{{domxref("HTMLSelectElement.willValidate")}}{{ReadOnlyInline}}</dt> + <dd>A {{jsxref("Boolean")}} that indicates whether the button is a candidate for constraint validation. It is false if any conditions bar it from constraint validation.</dd> +</dl> + +<h2 id="Methods">Methods</h2> + +<p><em>This interface inherits the methods of {{domxref("HTMLElement")}}, and of {{domxref("Element")}} and {{domxref("Node")}}.</em></p> + +<dl> + <dt>{{domxref("HTMLSelectElement.add()")}}</dt> + <dd>Adds an element to the collection of <code>option</code> elements for this <code>select</code> element.</dd> + <dt>{{domxref("HTMLSelectElement.blur()")}}{{obsolete_inline}}</dt> + <dd>Removes input focus from this element. <em>This method is now implemented on {{domxref("HTMLElement")}}</em>.</dd> + <dt>{{domxref("HTMLSelectElement.checkValidity()")}}</dt> + <dd>Checks whether the element has any constraints and whether it satisfies them. If the element fails its constraints, the browser fires a cancelable {{event("invalid")}} event at the element (and returns <code>false</code>).</dd> + <dt>{{domxref("HTMLSelectElement.focus()")}}{{obsolete_inline}}</dt> + <dd>Gives input focus to this element. <em>This method is now implemented on {{domxref("HTMLElement")}}</em>.</dd> + <dt>{{domxref("HTMLSelectElement.item()")}}</dt> + <dd>Gets an item from the options collection for this {{HTMLElement("select")}} element. You can also access an item by specifying the index in array-style brackets or parentheses, without calling this method explicitly.</dd> + <dt>{{domxref("HTMLSelectElement.namedItem()")}}</dt> + <dd>Gets the item in the options collection with the specified name. The name string can match either the <code>id</code> or the <code>name</code> attribute of an option node. You can also access an item by specifying the name in array-style brackets or parentheses, without calling this method explicitly.</dd> + <dt>{{domxref("HTMLSelectElement.remove()")}}</dt> + <dd>Removes the element at the specified index from the options collection for this select element.</dd> + <dt>{{domxref("HTMLSelectElement.setCustomValidity()")}}</dt> + <dd>Sets the custom validity message for the selection element to the specified message. Use the empty string to indicate that the element does <em>not</em> have a custom validity error.</dd> +</dl> + +<h2 id="範例">範例</h2> + +<h3 id="Get_information_about_the_selected_option">Get information about the selected option</h3> + +<pre class="brush: js">/* assuming we have the following HTML +<select id='s'> + <option>First</option> + <option selected>Second</option> + <option>Third</option> +</select> +*/ + +var select = document.getElementById('s'); + +// return the index of the selected option +console.log(select.selectedIndex); // 1 + +// return the value of the selected option +console.log(select.options[select.selectedIndex].value) // Second +</pre> + +<p>A better way to track changes to the user's selection is to watch for the {{event("change")}} event to occur on the <code><select></code>. This will tell you when the value changes, and you can then update anything you need to. See <a href="/en-US/docs/Web/Events/change#Example_Change_event_on_a_select">the example provided</a> in the documentation for the <code>change</code> event for details.</p> + +<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('HTML WHATWG', '#htmlselectelement', 'HTMLSelectElement')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>Since the latest snapshot, {{SpecName('HTML5 W3C')}}, it adds the <code>autocomplete</code> property and the <code>reportValidity()</code> method.</td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', 'forms.html#htmlselectelement', 'HTMLSelectElement')}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>Is a snapshot of {{SpecName("HTML WHATWG")}}.<br> + It adds the <code>autofocus</code>, <code>form</code>, <code>required</code>, <code>labels</code>, <code>selectedOptions</code>, <code>willValidate</code>, <code>validity</code> and <code>validationMessage</code> properties.<br> + The <code>tabindex</code> property and the <code>blur()</code> and <code>focus()</code> methods have been moved to {{domxref("HTMLElement")}}.<br> + The methods <code>item()</code>, <code>namedItem()</code>, <code>checkValidity()</code> and <code>setCustomValidity()</code>.</td> + </tr> + <tr> + <td>{{SpecName('DOM2 HTML', 'html.html#ID-94282980', 'HTMLSelectElement')}}</td> + <td>{{Spec2('DOM2 HTML')}}</td> + <td><code>options</code> now returns an {{domxref("HTMLOptionsCollection")}}.<br> + <code>length</code> now returns an <code>unsigned long</code>.</td> + </tr> + <tr> + <td>{{SpecName('DOM1', 'level-one-html.html#ID-94282980', 'HTMLSelectElement')}}</td> + <td>{{Spec2('DOM1')}}</td> + <td>Initial definition</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>1.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(1.0)}} <sup>[2]</sup></td> + <td>1.0</td> + <td>1.0</td> + <td>1.0</td> + </tr> + <tr> + <td><code>item()</code> and <code>namedItem()</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}<sup>[3]</sup></td> + <td>{{CompatGeckoDesktop(2.0)}}</td> + <td>8<sup>[3]</sup></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>setCustomValidity()</code>, <code>checkValidity()</code>, <code>willValidate</code>, <code>validationMessage</code>, <code>validity</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(2.0)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>selectedOptions</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(26)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>labels</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop(56)}}<sup>[1]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>1.0</td> + <td>1.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile(1)}}</td> + <td>1.0</td> + <td>1.0</td> + <td>1.0</td> + <td>1.0</td> + </tr> + <tr> + <td><code>item()</code> and <code>namedItem()</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile(2.0)}}</td> + <td>1.0</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>setCustomValidity()</code>, <code>checkValidity()</code>, <code>willValidate</code>, <code>validationMessage</code>, <code>validity</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile(2.0)}}</td> + <td>1.0</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>selectedOptions</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile(26)}}</td> + <td>1.2</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>labels</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile(56)}}<sup>[1]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Implemented in {{bug("556743")}}.</p> + +<p>[2] Historically, Firefox has allowed keyboard and mouse events to bubble up from the <code><option></code> element to the parent {{HTMLElement("select")}} element. This doesn't happen in Chrome, however, although this behavior is inconsistent across many browsers. For better Web compatibility (and for technical reasons), when Firefox is in multi-process mode and the <code><select></code> element is displayed as a drop-down list. The behavior is unchanged if the <code><select></code> is presented inline and it has either the <code>multiple</code> attribute defined or a <code>size</code> attribute set to more than 1. Rather than watching <code><option></code> elements for events, you should watch for {event("change")}} events on {{HTMLElement("select")}}. See {{bug(1090602)}} for details.</p> + +<p>[3] namedItem does not appear to take the <code>name</code> attribute into account (only the <code>id</code> attribute) on Internet Explorer and Edge. There is a <a href="https://connect.microsoft.com/IE/feedbackdetail/view/2414092/">bug report</a> to Microsoft about this.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>The {{HTMLElement("select")}} HTML element, which implements this interface.</li> +</ul> diff --git a/files/zh-tw/web/api/htmlselectelement/setcustomvalidity/index.html b/files/zh-tw/web/api/htmlselectelement/setcustomvalidity/index.html new file mode 100644 index 0000000000..54e47edf3c --- /dev/null +++ b/files/zh-tw/web/api/htmlselectelement/setcustomvalidity/index.html @@ -0,0 +1,50 @@ +--- +title: HTMLSelectElement.setCustomValidity() +slug: Web/API/HTMLSelectElement/setCustomValidity +translation_of: Web/API/HTMLSelectElement/setCustomValidity +--- +<div>{{ APIRef("HTML DOM") }}</div> + +<p><code><strong>HTMLSelectElement.setCustomValidity()</strong></code> 方法可為指定的元素設定自定義檢核訊息。使用空字串表示元素<em>沒有</em>發生違反自定檢核條件的錯誤。</p> + +<h2 id="語法">語法</h2> + +<pre class="eval language-html"><code class="language-html"><em>selectElt</em>.setCustomValidity(<em>string</em>);</code></pre> + +<h3 id="參數">參數</h3> + +<ul> + <li><em>string</em> 為 {{domxref("DOMString")}}，代表錯誤訊息。</li> +</ul> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">意見</th> + </tr> + <tr> + <td>{{SpecName('HTML WHATWG', '#dom-cva-setcustomvalidity', 'HTMLSelectElement.setCustomValidity()')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>No change since the latest snapshot, {{SpecName('HTML5 W3C')}}.</td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', 'forms.html#dom-cva-setcustomvalidity', 'HTMLSelectElement.setCustomValidity()')}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>Initial definition, snapshot of {{SpecName('HTML WHATWG')}}</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{Compat("api.HTMLSelectElement.setCustomValidity")}}</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/zh-TW/docs/Web/Guide/HTML/HTML5/Constraint_validation">表單驗證</a></li> +</ul> diff --git a/files/zh-tw/web/api/idbdatabase/index.html b/files/zh-tw/web/api/idbdatabase/index.html new file mode 100644 index 0000000000..843eac92f5 --- /dev/null +++ b/files/zh-tw/web/api/idbdatabase/index.html @@ -0,0 +1,219 @@ +--- +title: IDBDatabase +slug: Web/API/IDBDatabase +translation_of: Web/API/IDBDatabase +--- +<p>{{APIRef("IndexedDB")}}</p> + +<div> +<p>The <strong><code>IDBDatabase</code></strong> interface of the IndexedDB API provides a <a href="/en-US/docs/IndexedDB#database_connection">connection to a database</a>; you can use an <code>IDBDatabase</code> object to open a <a href="/en-US/docs/IndexedDB#gloss_transaction">transaction</a> on your database then create, manipulate, and delete objects (data) in that database. The interface provides the only way to get and manage versions of the database.</p> + +<p>{{AvailableInWorkers}}</p> +</div> + +<div class="note"> +<p><strong>Note</strong>: Everything you do in IndexedDB always happens in the context of a <a href="/en-US/docs/IndexedDB/Basic_Concepts_Behind_IndexedDB#gloss_transaction">transaction</a>, representing interactions with data in the database. All objects in IndexedDB — including object stores, indexes, and cursors — are tied to a particular transaction. Thus, you cannot execute commands, access data, or open anything outside of a transaction.</p> +</div> + +<div class="note"> +<p><strong>Note</strong>: Note that as of Firefox 40, IndexedDB transactions have relaxed durability guarantees to increase performance (see {{Bug("1112702")}}.) Previously in a <code>readwrite</code> transaction {{domxref("IDBTransaction.oncomplete")}} was fired only when all data was guaranteed to have been flushed to disk. In Firefox 40+ the <code>complete</code> event is fired after the OS has been told to write the data but potentially before that data has actually been flushed to disk. The <code>complete</code> event may thus be delivered quicker than before, however, there exists a small chance that the entire transaction will be lost if the OS crashes or there is a loss of system power before the data is flushed to disk. Since such catastrophic events are rare most consumers should not need to concern themselves further. If you must ensure durability for some reason (e.g. you're storing critical data that cannot be recomputed later) you can force a transaction to flush to disk before delivering the <code>complete</code> event by creating a transaction using the experimental (non-standard) <code>readwriteflush</code> mode (see {{domxref("IDBDatabase.transaction")}}.</p> +</div> + +<h2 id="Methods">Methods</h2> + +<p>Inherits from: <a href="/en-US/docs/DOM/EventTarget">EventTarget</a></p> + +<dl> + <dt>{{domxref("IDBDatabase.close()")}}</dt> + <dd>Returns immediately and closes the connection to a database in a separate thread.</dd> + <dt>{{domxref("IDBDatabase.createObjectStore()")}}</dt> + <dd>Creates and returns a new object store or index.</dd> + <dt>{{domxref("IDBDatabase.deleteObjectStore()")}}</dt> + <dd>Destroys the object store with the given name in the connected database, along with any indexes that reference it.</dd> + <dt>{{domxref("IDBDatabase.transaction()")}}</dt> + <dd>Immediately returns a transaction object ({{domxref("IDBTransaction")}}) containing the {{domxref("IDBTransaction.objectStore")}} method, which you can use to access your object store. Runs in a separate thread.</dd> +</dl> + +<h2 id="屬性">屬性</h2> + +<dl> + <dt>{{domxref("IDBDatabase.name")}} {{readonlyInline}}</dt> + <dd>A {{ domxref("DOMString") }} that contains the name of the connected database.</dd> + <dt>{{domxref("IDBDatabase.version")}} {{readonlyInline}}</dt> + <dd>A <a href="/en-US/docs/NSPR_API_Reference/Long_Long_(64-bit)_Integers">64-bit integer</a> that contains the version of the connected database. When a database is first created, this attribute is an empty string.</dd> + <dt>{{domxref("IDBDatabase.objectStoreNames")}} {{readonlyInline}}</dt> + <dd>A {{ domxref("DOMStringList") }} that contains a list of the names of the <a href="/en-US/docs/IndexedDB#gloss_object_store">object stores</a> currently in the connected database.</dd> +</dl> + +<h3 id="Event_handlers">Event handlers</h3> + +<dl> + <dt>{{domxref("IDBDatabase.onabort")}}</dt> + <dd>Fires when access of the database is aborted.</dd> + <dt>{{domxref("IDBDatabase.onerror")}}</dt> + <dd>Fires when access to the database fails.</dd> + <dt>{{domxref("IDBDatabase.onversionchange")}}</dt> + <dd> + <p>Fires when a database structure change ({{domxref("IDBOpenDBRequest.onupgradeneeded")}} event or<code> </code>{{domxref("IDBFactory.deleteDatabase")}} was requested elsewhere (most probably in another window/tab on the same computer). This is different from the version change transaction (see {{domxref("IDBVersionChangeEvent")}}), but it is related.</p> + </dd> +</dl> + +<h2 id="example" name="example">範例</h2> + +<p>In the following code snippet, we open a database asynchronously ({{domxref("IDBFactory")}}), handle success and error cases, and create a new object store in the case that an upgrade is needed ({{ domxref("IDBdatabase") }}). For a complete working example, see our <a href="https://github.com/mdn/to-do-notifications/">To-do Notifications</a> app (<a href="http://mdn.github.io/to-do-notifications/">view example live</a>.)</p> + +<pre class="brush: js;highlight:[13,24,26,27,28,32]">// Let us open our database + var DBOpenRequest = window.indexedDB.open("toDoList", 4); + + // these two event handlers act on the IDBDatabase object, when the database is opened successfully, or not + DBOpenRequest.onerror = function(event) { + note.innerHTML += '<li>Error loading database.</li>'; + }; + + DBOpenRequest.onsuccess = function(event) { + note.innerHTML += '<li>Database initialised.</li>'; + + // store the result of opening the database in the db variable. This is used a lot later on + db = DBOpenRequest.result; + + // Run the displayData() function to populate the task list with all the to-do list data already in the IDB + displayData(); + }; + + // This event handles the event whereby a new version of the database needs to be created + // Either one has not been created before, or a new version number has been submitted via the + // window.indexedDB.open line above + + DBOpenRequest.onupgradeneeded = function(event) { + var db = event.target.result; + + db.onerror = function(event) { + note.innerHTML += '<li>Error loading database.</li>'; + }; + + // Create an objectStore for this database using IDBDatabase.createObjectStore + + var objectStore = db.createObjectStore("toDoList", { keyPath: "taskTitle" }); + + // define what data items the objectStore will contain + + objectStore.createIndex("hours", "hours", { unique: false }); + objectStore.createIndex("minutes", "minutes", { unique: false }); + objectStore.createIndex("day", "day", { unique: false }); + objectStore.createIndex("month", "month", { unique: false }); + objectStore.createIndex("year", "year", { unique: false }); + + objectStore.createIndex("notified", "notified", { unique: false }); + + note.innerHTML += '<li>Object store created.</li>'; + };</pre> + +<p>This next line opens up a transaction on the Database, then opens an object store that we can then manipulate the data inside of.</p> + +<pre class="brush: js"> var objectStore = db.transaction('toDoList').objectStore('toDoList'); </pre> + +<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('IndexedDB', '#idl-def-IDBDatabase', 'IDBDatabase')}}</td> + <td>{{Spec2('IndexedDB')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility" name="Browser_compatibility">Browser compatibility</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>23{{property_prefix("webkit")}}<br> + 24</td> + <td>10 {{property_prefix("moz")}}<br> + {{CompatGeckoDesktop("16.0")}}</td> + <td>10, partial</td> + <td>15</td> + <td>7.1</td> + </tr> + <tr> + <td>Available in workers</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("37.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>4.4</td> + <td>{{CompatGeckoMobile("22.0")}}</td> + <td>1.0.1</td> + <td>10</td> + <td>22</td> + <td>8</td> + </tr> + <tr> + <td>Available in workers</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("37.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div class="warning"> +<p><strong>Important</strong>: Be careful in Chrome as it still implements the old specification along with the new one. Similarly it still has the prefixed <code>webkitIndexedDB</code> property even if the unprefixed <code>indexedDB</code> is present.</p> +</div> + +<h2 id="閱讀更多">閱讀更多</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/IndexedDB_API/Using_IndexedDB">Using IndexedDB</a></li> + <li>Starting transactions: {{domxref("IDBDatabase")}}</li> + <li>Using transactions: {{domxref("IDBTransaction")}}</li> + <li>Setting a range of keys: {{domxref("IDBKeyRange")}}</li> + <li>Retrieving and making changes to your data: {{domxref("IDBObjectStore")}}</li> + <li>Using cursors: {{domxref("IDBCursor")}}</li> + <li>Reference example: <a class="external" href="https://github.com/mdn/to-do-notifications/tree/gh-pages">To-do Notifications</a> (<a class="external" href="http://mdn.github.io/to-do-notifications/">view example live</a>.)</li> +</ul> + +<p> </p> diff --git a/files/zh-tw/web/api/index.html b/files/zh-tw/web/api/index.html new file mode 100644 index 0000000000..982a2aa3c0 --- /dev/null +++ b/files/zh-tw/web/api/index.html @@ -0,0 +1,15 @@ +--- +title: Web APIs +slug: Web/API +tags: + - API + - DOM + - JavaScript + - Reference +translation_of: Web/API +--- +<p>當你使用 JavaScript 為網站寫程式碼時，有很多很棒的 API 可以使用。</p> + +<p>以下清單列出所有能夠用在你開發網路程式或網站時的介面（即是物件的類型）。</p> + +<div>{{APIListAlpha}}</div> diff --git a/files/zh-tw/web/api/indexeddb_api/basic_concepts_behind_indexeddb/index.html b/files/zh-tw/web/api/indexeddb_api/basic_concepts_behind_indexeddb/index.html new file mode 100644 index 0000000000..a57486e7b2 --- /dev/null +++ b/files/zh-tw/web/api/indexeddb_api/basic_concepts_behind_indexeddb/index.html @@ -0,0 +1,209 @@ +--- +title: IndexedDB基礎概念 +slug: Web/API/IndexedDB_API/Basic_Concepts_Behind_IndexedDB +translation_of: Web/API/IndexedDB_API/Basic_Concepts_Behind_IndexedDB +--- +<p><strong>IndexedDB </strong>用來儲存資料到使用者的瀏覽器，所以我們的網頁應用程式不論在線上或線下都可以運作。IndexedDB 對需要儲存大量資料上 (如儲存 DVD 出租型錄) 的應用和不用一直存取網路的應用 (如郵件客戶端瀏覽、代辦事項、記事本等) 來說十分好用。</p> + +<h2 id="關於本文">關於本文</h2> + +<p>本文介紹 IndexedDB 重要概念和專有名詞，旨在提供 IndexedDB 全貌和關鍵概念，如要了解更多 IndexedDB 專有名詞，請參照<a href="https://developer.mozilla.org/zh-TW/docs/IndexedDB/Basic_Concepts_Behind_IndexedDB#definitions">定義</a>部分。</p> + +<p>想了解如何使用相關 API，請參照<a href="https://developer.mozilla.org/en-US/docs/IndexedDB/Using_IndexedDB">使用 IndexedDB</a>；相關參考資料請參照 <a href="https://developer.mozilla.org/zh-TW/docs/IndexedDB">IndexedDB</a> 一文，該文介紹了 IndexedDB 使用物件型態以及同步和非同步 API 。</p> + +<h2 id="IndexedDB_概要">IndexedDB 概要</h2> + +<p>IndexedDB 讓我們透過資料鍵 (key) 儲存、取回物件。所有對資料庫的變更都發生在交易操作；如同大部分網頁儲存方案，IndexedDB 遵守<a href="https://developer.mozilla.org/zh-TW/docs/JavaScript/Same_origin_policy_for_JavaScript">同源政策</a>，也就是說我們只能存取同網域下的資料。</p> + +<p>API 有分<a href="/en/IndexedDB#Asynchronous_API" title="https://developer.mozilla.org/en/IndexedDB#Asynchronous_API">非同步</a>和<a href="/en/IndexedDB#Synchronous_API" title="https://developer.mozilla.org/en/IndexedDB#Synchronous_API">同步</a>，非同步 API 適用於大部分情況，包括 <a href="https://developer.mozilla.org/zh-TW/docs/Web/Guide/Performance/Using_web_workers">Web Worker</a>，而同步 API 應該只用在 Web Worker 內。目前主流瀏覽器尚不支援同步 API，不過即使同步 API 存在，大部分的情況還是以非同步 API 使用為主。</p> + +<p>W3C 在 2011/11/18 宣布 WebSQL 已棄用，請用 IndexedDB 作為替代方案。IndexedDB 和 WebSQL 雖然都是儲存方案，但功能並不相同，IndexedDB 是索引資料表資料庫，而 WebSQL 是關聯式資料庫系統。</p> + +<h2 id="concepts" name="concepts">概念總覽</h2> + +<p>請將你在其他類型資料庫上的預期從 IndexedDB 上拋開，然後謹記以下重要概念:</p> + +<ul> + <li> + <p><strong>IndexedDB 資料庫儲存資料鍵對資料值的成對資料 (key-value pairs) 。</strong>資料值可以是複雜的結構化物件，資料鍵可以是這些物件的屬性，然後我們可以依物件屬性建立索引，進行資料搜尋以及排序。</p> + </li> + <li> + <p><strong>IndexedDB 建基於交易性質資料庫模型 (transactional database model) 。</strong>任何在 IndexedDB 上進行的操作都是屬於<a href="#gloss_transaction">交易 (transaction</a>)，IndexedDB API 提供了索引、資料表等等許多物件，然而這些物件都鎖定到某一個特定交易，所以我們不行在交易範疇外執行指令等操作。</p> + + <p>交易具有生命週期，所以交易結束後又操作交易會引起例外錯誤，而且交易是自動執行生效的，無法手動執行生效。</p> + + <p>想想看如果一個使用者在兩個頁面開啟同一個網路應用程式時，若是沒有交易機制，這兩個頁面對資料庫的存取操作將會產生衝突，因此交易機制是一個相當有用的機制。如果不清楚何謂交易，請參照底下<a href="#gloss_transaction">交易定義</a>部分和<a href="https://en.wikipedia.org/wiki/Database_transaction">維基百科交易相關文章</a>。</p> + </li> + <li> + <p><strong>IndexedDB 大部分 API 都是非同步類別。</strong>IndexedDB API 不會回傳資料，相反地，我們需要傳入回呼函數 (Callback function) 。我們並非直接、同步地儲存和取得資料，我們是請求資料庫作業，當作業結束時 DOM 事件再通知我們作業結束，然後我們再透過事件類別判斷作業成功或失敗；或許以上作法一開始聽起來有點複雜，不過之所以會如此做是有其背後道理的，而且這種作法和 <a href="https://developer.mozilla.org/zh-TW/docs/DOM/XMLHttpRequest">XMLHttpRequest</a> 相去不遠。</p> + </li> + <li> + <p><strong>IndexedDB 透過 DOM 事件通知作業結果。</strong>DOM 事件具有一個 typ e屬性 (在 IndexedDB 中，這個屬性幾乎不是 ”success” 就是 ”error” )，DOM 事件還有一個 target 屬性告訴我們事件進行目標，絕大多數情況下，事件的 target 皆為操作資料庫結果產生的 IDBRequest 物件。成功事件不會往上傳播而且無法取消，失敗事件會往上傳播但可取消，請謹記這點，因為正在進行的交易會因為失敗事件而中止，除非取消失敗事件。</p> + </li> + <li> + <p><strong>IndexedDB 隨處都在使用請求 (Request) 。</strong>接收前述成功或失敗 DOM 事件的物件就是請求，請求有 onsuccess 和 onerror 屬性以及 addEventListener 和 removeEventListener 方法，他們還有 readyState, result 與 errorCode 屬性告訴我們請求狀態，尤其 result 屬性相當奇妙，它可以代表各式不同意義，就看我們是如何建立請求，比如說，一個 IDBCursor 物件或剛存入資料庫的資料的資料鍵。</p> + </li> + <li> + <p><strong>IndexedDB 乃是物件導向的。</strong>IndexedDB 非關聯式資料庫，沒有資料表，這一點深深影響著應用程式如何設計。</p> + + <p>傳統關聯式資料庫中存著由資料列和屬性欄所構成的資料表，另一方面，IndexedDB 存的是某一個資料型態的物件存檔 (Object store)，IndexedDB 就只是保存存檔的 Javascript 物件；每一個物件存檔能具備一連串索引用以搜尋和排列資料，如果沒有聽過物件導向資料管理系統庫，可以去<a href="https://en.wikipedia.org/wiki/Object_database">維基百科物件資料庫</a>看看。</p> + </li> + <li> + <p><strong>IndexedDB 沒有結構化查詢語言 (Structured Query Language, SQL) 。</strong>IndexedDB 查詢索引以取得指標 (Cursor)，然後我們再用指標一一存取查詢結果，如果沒有聽過 NoSQL 系統，請去<a href="https://en.wikipedia.org/wiki/NoSQL">維基百科 NoSQL</a> 看看。</p> + </li> + <li> + <p><strong>IndexedDB 遵守同源政策 (Same-origin policy) 。</strong>URL 的網域、應用層協定和埠號構成來源，每一個來源皆有其獨特關聯的資料庫，每一個資料庫都有名稱辨識其所在來源。</p> + + <p><a href="https://developer.mozilla.org/zh-TW/docs/JavaScript/Same_origin_policy_for_JavaScript">同源政策</a>限制了 IndexedDB 存取其他來源下的資料，例如來自 http://www.example.com/app/ 的應用能夠存取 http://www.example.com/dir/ 下的資料，因為他們其實來自同一個來源，但無法存取 http://www.example.com:8080/dir/ (埠號不同) 或 https://www.example.com/dir/ (協定不同) 的資料，因為來源不同。</p> + </li> +</ul> + +<h2 id="definitions" name="definitions">定義</h2> + +<p>以下是 IndexedDB API 專有名詞定義與解說。</p> + +<h3 id="database" name="database">Database</h3> + +<dl> + <dt><a name="gloss_database">資料庫</a></dt> + <dd>資訊集中存放之處，由一或數個<a href="#gloss_object_store" title="#gloss_object_store">物件存檔 (Object store)</a> 組成，每一個資料庫必須具有: + <ul> + <li>名稱。用以辨識資料庫所屬來源，在生命週期間固定不變，可以任意字串 (甚至空白字串) 。</li> + <li> + <p>目前<a href="#gloss_version">版本</a>。當資料庫創建後，如未指定，它的版本是整數1。每一個資料庫同一時間只能有一個版本。</p> + </li> + </ul> + </dd> + <dt><a name="gloss_object_store">物件存檔 (object store</a>)</dt> + <dd> + <p>資料存放於資料庫的機制；物件存檔持有紀錄，也就是資料鍵和資料值的成對紀錄。記錄在物件存檔中依<em><a href="#gloss_key">資料鍵 (keys)</a></em>大小由小到大排列。</p> + + <p>每一個物件存檔都具備獨特名稱，物件存檔能夠選擇性地持有 <em><a href="#gloss_keygenerator">key generator</a> </em>和 <em><a href="#gloss_keypath">key path</a></em>；若有 key path 便會採用 <em><a href="#gloss_inline_key">in-line keys</a></em>，否則便採用 <em><a href="#gloss_outofline_key">out-of-line keys</a></em>。</p> + + <p>更多物件存檔細節，請參照 <a href="../../../../en/IndexedDB/IDBObjectStore" rel="internal">IDBObjectStore</a> 或 <a href="../../../../en/IndexedDB/IDBObjectStoreSync" rel="internal">IDBObjectStoreSync</a>。</p> + </dd> + <dt><a name="gloss_version">版本 (version</a>)</dt> + <dd>當資料庫創建後，如未指定，它的版本是整數 1；每一個資料庫同一時間只能有一個版本，唯一變更版本的方法是開啟比目前更大的版本，變更版本將啟動 versionchange 交易並且觸發 upgradeneeded 事件，upgradeneeded 事件處理器也是唯一可以變更資料庫結構之處。</dd> + <dd><strong>注意: </strong>本處解說涵蓋<a href="http://dvcs.w3.org/hg/IndexedDB/raw-file/tip/Overview.html">近期大部分規範</a>，舊版瀏覽器支援現在已經廢棄的 <a href="/en-US/docs/IndexedDB/IDBDatabase#setVersion()">IDBDatabase.setVersion()</a> 方法。</dd> + <dt> </dt> + <dt><a name="gloss_database_connection">database connection</a></dt> + <dd>開啟資料庫的作業，一個資料庫同一時間可以擁有多個連線。</dd> + <dt><a name="gloss_transaction">交易 (transaction</a>)</dt> + <dd> + <p>在特定資料庫上進行資料存取和資料修改的一連串作業，這便是我們和資料庫的互動，事實上，任何讀取或變更資料庫資料都會發生在交易之中。</p> + + <p>只要寫入交易間沒有重疊<a href="https://developer.mozilla.org/zh-TW/docs/IndexedDB/Basic_Concepts_Behind_IndexedDB#range">範疇 (<em>scopes)</em></a>，一個資料庫連結可以同時擁有多個進行中交易。交易範疇在交易創建當下決定，交易範疇定義了與交易互動的物件存檔以及將交易期間不可變更部分，例如說，有一個資料庫連結正在進行寫入交易，這項寫入交易涵蓋 flyingMonkey 物件存檔，我們可以進行第二項有關 unicornCentaur 與 unicornPegasus 物件存檔的交易。至於讀取交易則不受交易範疇重疊限制。</p> + + <p>交易的生命應該不可過長，所以瀏覽器可以終止交易時間過長的交易，好讓長時間被鎖定的資料得以解除鎖定；交易可以中止，中止後交易所造成的變更都會被復原；交易的中止不必要等到交易開始或進行中。</p> + + <p>交易有三種模式: <code>readwrite</code>, <code>readonly </code>和 <code>versionchange</code>，只能透過 versionchange 交易創建、刪除物件存檔與索引。</p> + + <p>由於交易是相當重要的觀念，尤其是交易和版本間的關係，請參照 <a href="../../../../en/IndexedDB/IDBTransaction" rel="internal">IDBTransaction</a> 以了解更多交易相<br> + 關細節，另外關於同步API，請參照<a href="http://../../../../en/IndexedDB/IDBTransactionSync" rel="internal">IDBTransactionSync</a>。</p> + </dd> + <dt><a name="gloss_request">請求 (request</a>)</dt> + <dd>每一個讀寫作業都是一個請求。</dd> + <dt><a name="gloss_index">索引 (index</a>)</dt> + <dd> + <p>一個用來查詢其他物件存檔內紀錄的特殊物件存檔，被查詢的物件存檔我們稱為參照物件存檔 (referenced object store) 。索引是資料鍵和值的成對紀錄，其中值就是參照物件存檔內的記錄的資料鍵；當參照物件存檔有紀錄新增、變更或刪除時索引內的紀錄也會相應自動產生，索引內的紀錄只能指向參照物件存檔內的一筆紀錄，但可以有多筆索引紀錄參照同一個物件存檔。物件存檔變更同時，所有的相關索引也會自動相應更新。</p> + + <p>除此之外，我們也可以透過<a href="#gloss_key">資料鍵 (key)</a> 來查詢物件存檔中的紀錄。</p> + + <p>了解如何使用索引請參照<a href="/en/IndexedDB/Using_IndexedDB#Using_an_index">使用 IndexedDB</a>，要知道更多索引細節請參照 <a href="http://../../../../en/IndexedDB/IDBKeyRange" rel="internal">IDBKeyRange</a> 和 <a href="https://developer.mozilla.org/en-US/docs/IndexedDB/IDBIndex">IDBIndex</a> 。</p> + </dd> +</dl> + +<h3 id="key" name="key">資料鍵 (Key) 和資料值 (Value)</h3> + +<dl> + <dt><a name="gloss_key">資料鍵 (key</a>)</dt> + <dd> + <p>資料存放在物件存檔中。物件存檔有三種方式產生資料鍵: 資料鍵產生器 (<em><a href="#gloss_keygenerator">k</a></em><em><a href="#gloss_keygenerator">ey generator</a></em>)、資料鍵路徑 (<em><a href="#gloss_keypath">key path</a></em>) 以及指定值。資料鍵的資料型態 (data type) 必須要是能夠進行大小排序；物件存檔中的每一筆紀錄都要有一支獨特的對應資料鍵，不能和同一個物件存檔中其他紀錄的資料鍵相同。</p> + + <p>資料鍵可以是: <a href="/en/JavaScript/Reference/Global_Objects/String" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">string</a>, <a href="/en/JavaScript/Reference/Global_Objects/Date" title="en/JavaScript/Reference/Global Objects/Date">date</a>, float和 <a href="/en/JavaScript/Reference/Global_Objects/Array">array (陣列)</a>；對於 array，資料鍵範圍可以是空值到無限，還可以在 array 中包含另一個 array，至於以字串或整數作資料鍵則無特殊規定。</p> + + <p>除此之外，我們也可以透過索引 (<em><a href="#gloss_index">index</a></em>) 來查詢物件存檔中的紀錄。</p> + </dd> + <dt><a name="gloss_keygenerator">資料鍵產生器 (key generator</a>)</dt> + <dd>自動生成有大小順序關係的資料鍵的機制；因為資料鍵是必要的，所以如果沒有資料鍵或想省去給定資料鍵的步驟，那就需要用產生器自動產生資料鍵。</dd> + <dt><a name="gloss_inline_key">in-line key</a></dt> + <dd>當物件存檔有資料鍵路徑時稱為有使用 in-line key。</dd> + <dt><a name="gloss_outofline_key">out-of-line key</a></dt> + <dd>當物件存檔沒有資料鍵路徑時稱為使用 out-of--line key。</dd> + <dt><a name="gloss_keypath">資料鍵路徑 (key path</a>)</dt> + <dd>定義瀏覽器應該如何從物件存檔資料值或索引中提取資料鍵。以下為有效的資料鍵路徑: 一個空字串、一個 Javascript 辨識名稱 (JavaScript identifier) 或數個由”.”(ASCII字元第46字碼) 分隔的 Javascript 辨識名稱。路徑不可含有空白字元。</dd> + <dt><a name="gloss_value">資料值 (value</a>)</dt> + <dd> + <p>每筆紀錄都有資料值，資料值可以是任意Javascript所能表達的項目，包括<a href="/en/JavaScript/Reference/Global_Objects/Boolean" rel="internal" title="en/JavaScript/Reference/Global_Objects/Boolean">boolean</a>, <a href="/en/JavaScript/Reference/Global_Objects/Number" rel="internal" title="en/JavaScript/Reference/Global_Objects/Number">number</a>, <a href="/en/JavaScript/Reference/Global_Objects/String" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">string</a>, <a href="/en/JavaScript/Reference/Global_Objects/Date" title="en/JavaScript/Reference/Global Objects/Date">date</a>, <a href="/en/JavaScript/Reference/Global_Objects/Object" title="en/JavaScript/Reference/Global Objects/Object">object</a>, <a href="/en/JavaScript/Reference/Global_Objects/Array" rel="internal" title="en/JavaScript/Reference/Global_Objects/Array">array</a>, <a href="/en/JavaScript/Reference/Global_Objects/RegExp" rel="internal" title="en/JavaScript/Reference/Global_Objects/RegExp">regexp</a>, <a href="/en/JavaScript/Reference/Global_Objects/undefined" title="en/JavaScript/Reference/Global_Objects/undefined">undefined</a> 以及 null。</p> + + <p>儲存物件或陣列裡的屬性和值也可以是任意Javascript所能表達的項目。</p> + + <p>可以儲存 <a href="/en/DOM/Blob" title="en/DOM/Blob">Blobs</a> 和檔案，請參照 <a href="http://www.w3.org/TR/IndexedDB/">W3C 規範</a>。</p> + </dd> +</dl> + +<h3 id="range" name="range">範圍和範疇</h3> + +<dl> + <dd><strong>範疇</strong></dd> + <dd>交易影響到的物件和索引。讀取交易間的範疇可以互相重疊、同時進行，然後寫入交易範疇則不可，如果同時開啟多項交易範疇相同的寫入交易的話，那麼這些交易會排入佇列 (queue)，一個接著一個完成後執行。</dd> + <dd><strong>指標 (Cursor)</strong></dd> + <dd>在一定資料鍵範圍以內往覆 (iterate) 資料的機制。指標指向了一個物件存檔或索引，它會在一定範圍內，由小到大或由大到小循著紀錄的資料鍵移動，詳細資訊請參照 <a href="../../../../en/IndexedDB/IDBCursor" rel="internal">IDBCursor</a> 或 <a href="../../../../en/IndexedDB/IDBCursorSync" rel="internal">IDBCursorSync</a> 。</dd> + <dd><strong>資料鍵範圍</strong></dd> + <dd> + <p>某種資料型態的一段連續區間，這個區間將作為資料鍵的上下限，我們透過資料鍵或資料鍵範圍取出物件存檔和索引值；藉由上下限我們可以做到存取資料鍵介於 x 和 y 之間的資料，詳細請參考 <a href="../../../../en/IndexedDB/IDBKeyRange" rel="internal">IDBKeyRange</a> 。</p> + </dd> +</dl> + +<h2 id="limitations" name="limitations">限制</h2> + +<p>IndexedDB 設計上足以滿足大部分客戶端儲存需求，不過，以下情況並不適用 IndexedDB :</p> + +<ul> + <li>多國語言排序。各國語言字串的排序不一定都一樣，所以 IndexedDB 無法處理多國語言字串排序。不過雖然 IndexedDB 無法處理多國語言字串排序，我們可以改為先讀出資料後再自行排序。</li> + <li>同步化。IndexedDB API 設計上並沒有考慮到和伺服器端資料庫同步化，所以客戶端和伺服器端資料庫同步需要我們自行處理。</li> + <li>全文搜尋。IndexedDB 沒有等同於 SQL 的 LIKE 的 API 。</li> +</ul> + +<p>除此之外，請小心瀏覽器可能會清空資料庫，例如:</p> + +<ul> + <li>使用者要求清空資料庫。許多瀏覽器讓使用者可以清空網站的 cookies、書籤、密碼和 IndexedDB 資料庫。</li> + <li>私密瀏覽。Firefox 和 Chrome 等瀏覽器提供私密瀏覽模式，當瀏覽結束後，資料庫會被清空。</li> + <li>超出硬碟空間或資料庫空間上限。</li> + <li>資料毀損。</li> + <li>當未來有不相容於現在的修改。</li> +</ul> + +<p>瀏覽器確切的狀況和功能範疇未來會變更，但基本上瀏覽器還是會盡可能保存資料。</p> + +<h2 id="next" name="next">下一步</h2> + +<p>現在我們已經了解 IndexedDB 的整體概念，接下來請到 <a href="/en/IndexedDB/Using_IndexedDB">“使用 IndexedDB”</a> 看看如何實際使用 IndexedDB。</p> + +<h2 id="延伸閱讀">延伸閱讀</h2> + +<p>標準規範</p> + +<ul> + <li><a href="http://www.w3.org/TR/IndexedDB/" title="http://www.w3.org/TR/IndexedDB/"><span style="direction: ltr;">Indexed Database API Specification</span></a></li> +</ul> + +<p>參照</p> + +<ul> + <li><a href="/en/IndexedDB" title="https://developer.mozilla.org/en/IndexedDB">IndexedDB API Reference</a></li> +</ul> + +<p>相關教學</p> + +<ul> + <li><a href="/en/IndexedDB/Using_IndexedDB" title="en/IndexedDB/IndexedDB primer">Using IndexedDB</a></li> + <li><a class="external" href="http://www.html5rocks.com/tutorials/indexeddb/todo/" title="http://www.html5rocks.com/tutorials/indexeddb/todo/">A simple TODO list using HTML5 IndexedDB</a><span class="external">. </span><span class="external"> {{ Note("請注意此教學範例用到的已經廢棄的<code>setVersion()方法。</code>") }}</span></li> +</ul> + +<p>相關文章</p> + +<ul> + <li><a class="external" href="http://msdn.microsoft.com/en-us/scriptjunkie/gg679063.aspx" title="http://msdn.microsoft.com/en-us/scriptjunkie/gg679063.aspx">IndexedDB — The Store in Your Browserr</a>Basic concepts</li> +</ul> diff --git a/files/zh-tw/web/api/indexeddb_api/index.html b/files/zh-tw/web/api/indexeddb_api/index.html new file mode 100644 index 0000000000..91f2fc812d --- /dev/null +++ b/files/zh-tw/web/api/indexeddb_api/index.html @@ -0,0 +1,148 @@ +--- +title: IndexedDB +slug: Web/API/IndexedDB_API +tags: + - Database + - IndexedDB + - bug-840092 +translation_of: Web/API/IndexedDB_API +--- +<div>{{SeeCompatTable}}</div> + +<p>IndexedDB 為用戶端的儲存用 API，可用於大量的結構化資料，並透過索引功能而高效率搜尋資料。<a href="https://developer.mozilla.org/zh-TW/docs/DOM/Storage" title="DOM/Storage">DOM Storage</a> 適合儲存較少量的資料；IndexedDB 則適合大量結構化資料的儲存方案。</p> + +<p>本篇文章僅為 API 物件的入門技術說明。若需進一步了解，則請參閱 <a href="https://developer.mozilla.org/zh-TW/docs/IndexedDB/Basic_Concepts_Behind_IndexedDB" title="IndexedDB/Basic_Concepts_Behind_IndexedDB">IndexedDB 基本概念</a>。更多細節則可參閱<a href="https://developer.mozilla.org/zh-TW/docs/IndexedDB/Using_IndexedDB" title="IndexedDB/Using_IndexedDB">使用 IndexedDB</a>。</p> + +<p>IndexedDB 提供不同 APIs 用於同步與非同步的存取作業。同步 API 僅能用於<a href="https://developer.mozilla.org/zh-TW/docs/DOM/Worker" title="Worker">Web Workers</a> 之中，但尚未有瀏覽器支援同步API。非同步 API 則用於 Web Workers 內外均可，但 Firefox 目前尚未建構。</p> + +<h2 id="非同步_API">非同步 API</h2> + +<p>非同步API不會阻塞呼叫它的執行緒。若要非同步存取資料庫，可於 <a href="https://developer.mozilla.org/zh-TW/docs/DOM/window" title="DOM/window">window</a> 物件的 <a href="https://developer.mozilla.org/zh-TW/docs/IndexedDB/IDBEnvironment#attr_indexedDB" title="IndexedDB/IDBEnvironment#attr indexedDB">indexedDB</a> 屬性上呼叫 <a href="https://developer.mozilla.org/zh-TW/docs/IndexedDB/IDBFactory#open" title="IndexedDB/IDBFactory#open">open</a>()。此函式將回傳 IDBRequest 物件 (IDBOpenDBRequest)，開始非同步存取資料庫；呼叫端程式利用IDBRequest物件上的事件來進行非同步溝通。</p> + +<div class="note"> +<p><strong>注意：</strong>在舊版瀏覽器 (Gecko 16 版之前的 indexedDB 屬性；Chrome 中的 webkitIndexedDB；IE 10 中的 msIndexedDB) 中的 indexedDB 物件，均具備前綴屬性。</p> +</div> + +<ul> + <li><a href="/zh-TW/docs/IndexedDB/IDBFactory" title="IndexedDB/IDBFactory"><code>IDBFactory</code></a> 可存取資料庫。此介面是透過全域物件 <code>indexedDB</code> 所建構，因此成為 API 的切入點。</li> + <li><a href="/zh-TW/docs/IndexedDB/IDBCursor" title="IndexedDB/IDBCursor"><code>IDBCursor</code></a> 將依序存取物件與索引。</li> + <li><a href="/zh-TW/docs/IndexedDB/IDBCursorWithValue"><code>IDBCursorWithValue</code></a> 將依序存取物件與索引，並回傳指標 (Cursor) 的目前數值。</li> + <li><a href="/zh-TW/docs/IndexedDB/IDBDatabase" title="IndexedDB/IDBDatabase"><code>IDBDatabase</code></a> 代表到資料庫的連線。這也是能與資料庫互動的唯一方式。</li> + <li><a href="/zh-TW/docs/IndexedDB/IDBEnvironment" title="IndexedDB/IDBEnvironment"><code>IDBEnvironment</code></a> 可存取用戶端的資料庫。此介面是透過 <a href="https://developer.mozilla.org/en-US/docs/DOM/window" title="../en-US/docs/DOM/window">window</a> 物件所建構。</li> + <li><a href="/zh-TW/docs/IndexedDB/IDBIndex" title="IndexedDB/IDBIndex"><code>IDBIndex</code></a> 可存取索引的Metadata。</li> + <li><code><a href="/zh-TW/docs/IndexedDB/IDBKeyRange" title="IndexedDB/KeyRange">IDBKeyRange</a></code> 定義資料鍵範疇。</li> + <li><a href="/zh-TW/docs/IndexedDB/IDBObjectStore" title="IndexedDB/IDBObjectStore"><code>IDBObjectStore</code></a> 代表物件存檔。</li> + <li><a href="/zh-TW/docs/IndexedDB/IDBOpenDBRequest" title="IndexedDB/IDBOpenDBRequest"><code>IDBOpenDBRequest</code></a> 代表「開啟資料庫」的請求。</li> + <li><a href="/zh-TW/docs/IndexedDB/IDBRequest" title="IndexedDB/IDBRequest"><code>IDBRequest</code></a> 代表向非同步資料庫和資料庫物件發出之請求，也就是呼叫非同步方法後回傳值。</li> + <li><a href="/zh-TW/docs/IndexedDB/IDBTransaction" title="IndexedDB/IDBTransaction"><code>IDBTransaction</code></a> 代表一個交易。我們可以和資料庫進行交易，例如要求存取某一個物件存檔，以及決定要執行讀或寫的存取作業。</li> + <li><a href="/zh-TW/docs/IndexedDB/IDBVersionChangeEvent" title="IDBVersionChangeEvent"><code>IDBVersionChangeEvent</code></a> <code>則代表資料庫所變更的版本。</code></li> +</ul> + +<p>以下API在早期規範中有定義，但現已移除。這邊列出僅供參考:</p> + +<ul> + <li><a href="https://developer.mozilla.org/zh-TW/docs/IndexedDB/IDBVersionChangeRequest" title="IndexedDB/IDBVersionChangeRequest">IDBVersionChangeRequest</a> 代表「更改資料庫版本」的請求。更改資料庫版本的方法已有不同 (呼叫 <a href="https://developer.mozilla.org/zh-TW/docs/IndexedDB/IDBFactory#open" title="IndexedDB/IDBFactory#open">IDBFactory.open()</a> 而不需同時呼叫 <a href="https://developer.mozilla.org/zh-TW/docs/IndexedDB/IDBDatabase#setVersion%28%29" title="IndexedDB/IDBDatabase#setVersion()">IDBDatabase.setVersion()</a>)；而且<a href="https://developer.mozilla.org/zh-TW/docs/IndexedDB/IDBOpenDBRequest" title="IndexedDB/IDBOpenDBRequest">IDBOpenDBRequest</a>已經整合了從IDBVersionChangeRequest中所移除之功能。</li> + <li><a href="https://developer.mozilla.org/zh-TW/docs/IndexedDB/IDBDatabaseException" title="IndexedDB/DatabaseException">IDBDatabaseException </a> {{obsolete_inline}} 在執行資料庫作業時，代表可能遭遇的例外狀況。</li> +</ul> + +<p>除了非同步API，也有應用在<a href="https://developer.mozilla.org/zh-TW/docs/DOM/Using_web_workers" title="Using_web_workers">WebWorkers</a>內的同步API，但請注意目前還沒有瀏覽器支援同步API。這裡也提供 <a href="https://developer.mozilla.org/zh-TW/docs/IndexedDB/Syncronous_API" title="IndexedDB/SyncronousAPI">API 的同步版本</a>。</p> + +<h2 id="儲存限制">儲存限制</h2> + +<p>單一資料庫項目的容量/大小並沒有任何限制，但是各個 IndexedDB資料庫的容量就有限制。此限制，還有使用者介面的斷言 (Assert) 方式，又將因瀏覽器而有所不同：</p> + +<ul> + <li> + <p>Firefox：對 IndexedDB 資料庫的容量並無限制。但若要儲存的 Blobs 超過 50 MB，使用者介面將會要求權限。若要修改此容量，則可透過 dom.indexedDB.warningQuota (可至 <a href="http://mxr.mozilla.org/mozilla-central/source/modules/libpref/src/init/all.js" title="http://mxr.mozilla.org/mozilla-central/source/modules/libpref/src/init/all.js">http://mxr.mozilla.org/mozilla-central/source/modules/libpref/src/init/all.js</a> 中設定) 設定自己所需的限制。</p> + </li> + <li>Google Chrome：請參閱 <a class="link-https" href="https://developers.google.com/chrome/whitepapers/storage#temporary" rel="freelink">https://developers.google.com/chrome...rage#temporary</a></li> +</ul> + +<h2 id="Example" name="Example">範例</h2> + +<p>Web 上的 IndexedDB 使用範例，是由 Marco Castelluccio 所提供。Marco 是 IndexedDB Mozilla DevDerby 的優勝者，而該得獎 Demo 為 <a href="https://developer.mozilla.org/zh-TW/demos/detail/elibri" title="demos/detail/elibri">eLibri</a>，屬於函式庫與 eBook 閱讀器的 App。</p> + +<h2 id="Browser_compatibility" name="Browser_compatibility">瀏覽器相容性</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 (WebKit)</th> + </tr> + <tr> + <td>Asynchronous API</td> + <td> + <p>24.0<br> + 11.0 {{property_prefix("webkit")}}</p> + </td> + <td> + <p>{{CompatGeckoDesktop("16.0")}}<br> + {{CompatGeckoDesktop("2.0")}} {{property_prefix("moz")}}</p> + </td> + <td>10 {{property_prefix("ms")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>Synchronous API<br> + (used with <a href="/zh-TW/docs/DOM/Using_web_workers" title="Using_web_workers">WebWorkers</a>)</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}<br> + See {{bug(701634)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</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>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Asynchronous API</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop("6.0")}} {{property_prefix("moz")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<p>瀏覽器相容性表格則請參閱：<a href="http://caniuse.com/indexeddb" title="http://caniuse.com/indexeddb">When Can I Use IndexedDB</a></p> + +<p>另可透過 <a href="https://github.com/axemclion/IndexedDBShim" title="https://github.com/axemclion/IndexedDBShim">IndexedDB Polyfill</a>，在<a href="http://caniuse.com/sql-storage" title="http://caniuse.com/sql-storage">支援 WebSQL 的瀏覽器</a>上使用 IndexedDB。</p> + +<h2 id="另可參閱">另可參閱</h2> + +<ul> + <li><a href="https://developer.mozilla.org/zh-TW/docs/IndexedDB/Basic_Concepts_Behind_IndexedDB" title="IndexedDB/Basic Concepts Behind IndexedDB">IndexedDB 基本概念</a></li> + <li><a href="https://developer.mozilla.org/zh-TW/docs/IndexedDB/Using_IndexedDB" title="IndexedDB/IndexedDB primer">使用 IndexedDB</a></li> + <li><a href="http://hacks.mozilla.org/2012/02/storing-images-and-files-in-indexeddb/" title="http://hacks.mozilla.org/2012/02/storing-images-and-files-in-indexeddb/">在 IndexedDB 中儲存影像與檔案</a></li> + <li><a href="http://www.html5rocks.com/tutorials/indexeddb/todo/" title="http://www.html5rocks.com/tutorials/indexeddb/todo/">使用 HTML5 IndexedDB 的簡易 TODO 清單</a><br> + {{Note("此線上教學是根據較舊版本的規格所列，因此無法搭配最新版的瀏覽器。新版本已移除其中的 <code>setVersion()</code> 函式。")}}</li> + <li><a href="http://www.w3.org/TR/IndexedDB/" title="http://www.w3.org/TR/IndexedDB/">Indexed Database API 規格</a></li> + <li><a href="http://msdn.microsoft.com/en-us/scriptjunkie/gg679063.aspx" title="http://msdn.microsoft.com/en-us/scriptjunkie/gg679063.aspx">IndexedDB — 儲存於自己的瀏覽器中</a></li> + <li><a href="http://nparashuram.com/IndexedDB/trialtool/index.html" title="http://nparashuram.com/IndexedDB/trialtool/index.html">IndexedDB 範例</a></li> + <li>僅支援 WebSQL 的瀏覽器 (例如行動 WebKit)，可適用 <a href="https://github.com/axemclion/IndexedDBShim" title="https://github.com/axemclion/IndexedDBShim">IndexedDB Polyfill</a></li> + <li><a href="http://nparashuram.com/IndexedDBShim/" title="http://nparashuram.com/IndexedDBShim/">JQuery IndexedDB 外掛程式</a></li> +</ul> diff --git a/files/zh-tw/web/api/indexeddb_api/using_indexeddb/index.html b/files/zh-tw/web/api/indexeddb_api/using_indexeddb/index.html new file mode 100644 index 0000000000..5bddd965b4 --- /dev/null +++ b/files/zh-tw/web/api/indexeddb_api/using_indexeddb/index.html @@ -0,0 +1,1085 @@ +--- +title: 使用IndexedDB +slug: Web/API/IndexedDB_API/Using_IndexedDB +translation_of: Web/API/IndexedDB_API/Using_IndexedDB +--- +<p>IndexedDB提供了在瀏覽器上儲存保留資料的功能，藉由它，不論是線上或線下我們的應用都可以進行資料存取。</p> +<h2 id="關於本文">關於本文</h2> +<p>本文會帶領各位操作非同步IndexedDB的API，如果不知道甚麼是IndexedDB，請先看看<a href="https://developer.mozilla.org/zh-TW/docs/IndexedDB/Basic_Concepts_Behind_IndexedDB">"IndexedDB基本礎念"</a>。</p> +<h2 id="pattern" name="pattern">基本操作步驟</h2> +<p>操作IndexedDB的基本步驟建議如下:</p> +<ol> + <li>開啟資料庫和交易(transaction)。</li> + <li>建立物件存檔(object store)</li> + <li>發出資料庫操作請求，例如新增或取得資料。</li> + <li> + <div> + 聆聽對應DOM事件等待操作完成。</div> + </li> + <li> + <div> + 從result物件上取得結果進行其他工作。</div> + </li> +</ol> +<p>好了，知道了上述概念後，我們可以來實際做些甚麼。</p> +<h2 id="open" name="open">建立和結構資料庫</h2> +<p>由於IndexedDB的標準仍在演進，所以目前一些實作還需要加上瀏覽器前綴標示(如Gecko基礎瀏覽器的前綴標示為moz，WebKit基礎瀏覽器的前綴標示為webkit)，瀏覽器的實作也可能會有所差異，不過一旦共識標準達成，無瀏覽器前綴標示實作將出現。其實，Internet Explorer 10, Firefox 16, Chrome 24已經有了無瀏覽器前綴標示實作。</p> +<h3 id="操作實驗性質的IndexedDB">操作實驗性質的IndexedDB</h3> +<p>如果需要試驗瀏覽器的前綴標示，可以如下:</p> +<pre class="brush: js">// In the following line, you should include the prefixes of implementations you want to test. +window.indexedDB = window.indexedDB || window.mozIndexedDB || window.webkitIndexedDB || window.msIndexedDB; +// DON'T use "var indexedDB = ..." if you're not in a function. +// Moreover, you may need references to some window.IDB* objects: +window.IDBTransaction = window.IDBTransaction || window.webkitIDBTransaction || window.msIDBTransaction; +window.IDBKeyRange = window.IDBKeyRange || window.webkitIDBKeyRange || window.msIDBKeyRange; +// (Mozilla has never prefixed these objects, so we don't need window.mozIDB*)</pre> +<p>請注意瀏覽器前綴標示的實作可能不完整、有些問題或仍然遵守舊版標準，因此不建議在正式版程式碼中使用。與其宣稱支援又有問題，倒不如直接不支援。</p> +<pre class="brush: js">if (!window.indexedDB) { + window.alert("Your browser doesn't support a stable version of IndexedDB. Such and such feature will not be available."); +} +</pre> +<h3 id="開啟資料庫">開啟資料庫</h3> +<p>開頭如下:</p> +<pre class="brush: js">// Let us open our database +var request = window.indexedDB.open("MyTestDatabase", 3); +</pre> +<p>注意到了嗎，開啟資料庫必須要進行請求。</p> +<p>開啟請求並不會立刻開啟資料庫或交易，呼叫open()方法會回傳一個<a href="/en-US/docs/IndexedDB/IDBOpenDBRequest" title="/en-US/docs/IndexedDB/IDBOpenDBRequest"><code>IDBOpenDBRequest</code></a>物件，這個物件擁有兩個事件(success和error)。大部分IndexedDB的非同步功能都會回傳一個<code style="font-size: 14px; color: rgb(51, 51, 51);"><a href="/en-US/docs/IndexedDB/IDBDatabase" title="/en-US/docs/IndexedDB/IDBDatabase">IDBDatabase</a></code>類物件，然後我們可以註冊成功和失敗事件處理器。</p> +<p>Open方法第二個參數是資料庫版本，資料庫版本決定了資料庫結構，也就是資料庫物件存檔的結構。如果請求版本不存在(比如因為這是一個新資料庫或是資料庫版本已升級)，onupgradeneeded事件會被觸發，然後我們可以在onupgradeneeded事件處理器中再建立新的版本，下面<a href="#Updating_the_version_of_the_database">升級資料庫版本</a>有更詳細的說明。</p> +<h4 id="產生事件處理器">產生事件處理器</h4> +<p>幾乎所有第一件要對請求做的事都是產生success和error事件處理器:</p> +<pre class="brush: js">request.onerror = function(event) { + // Do something with request.errorCode! +}; +request.onsuccess = function(event) { + // Do something with request.result! +};</pre> +<p>如果一切正常，success事件(也就是DOM事件的type屬性設為success)會以request為目標觸發，然後request物件上的onsuccess函數接著被呼叫，其中success事件就是參數；否則error事件(也就是DOM事件的type屬性設為error)會以request為目標觸發，然後request物件上的onerror函數接著被呼叫，其中error事件就是參數。</p> +<p>IndexedDB的API設計上盡量減少錯誤處理，所以不太常看到錯誤事件，不過開啟資料庫的時候還是有一些狀況會產產生錯誤，最常見的狀況是使用者拒絕我們建立資料庫。</p> +<p>IndexedDB設計目標之一為存放大量資料以供離線使用(請參考<a href="/en/IndexedDB#Storage_limits" title="https://developer.mozilla.org/en/IndexedDB#Storage_limits">"儲存限制"</a>了解更多細節)。但很明顯地，瀏覽器又不樂見一些廣告網站或惡意網站汙染電腦，所以當任一個網路應用第一次開啟IndexedDB資料庫，瀏覽器會徵詢使用者是否准許其作業；同時在私密瀏覽中開啟作業也會失敗，因為私密瀏覽不會留下任何瀏覽痕跡。</p> +<p>這裡呼叫indexedDB.open()開啟indexedDB資料庫並回傳request物件，假設使用者允許我們建立indexedDB資料庫，我們也收到suceess事件觸發了success回呼函數(callback)，request物件的result屬性會是一個IDBDatabase物件 ，接下來便是要儲存這個物件之後使用。下方是整個作業的示範程式碼:</p> +<pre class="brush: js">var db; +var request = indexedDB.open("MyTestDatabase"); +request.onerror = function(event) { + alert("Why didn't you allow my web app to use IndexedDB?!"); +}; +request.onsuccess = function(event) { + db = request.result; +}; +</pre> +<h4 id="錯誤處理">錯誤處理</h4> +<p>錯誤事件會向上傳遞；錯誤事件以產生錯誤之請求為目標觸發，然後一路傳遞到交易，最後到資料庫物件；如果不想要為每一個請求新增錯誤處理器，可以改為資料庫物件加入一個錯誤處理器。</p> +<pre class="brush: js">db.onerror = function(event) { + // Generic error handler for all errors targeted at this database's + // requests! + alert("Database error: " + event.target.errorCode); +}; +</pre> +<p>最常見的錯誤之一就是VER_ERR，該錯誤代表現在資料料庫版本大於嘗試開啟的資料庫版本，這項錯誤必須要有錯誤處理器處理。</p> +<h3 id="建立或更新資料庫版本">建立或更新資料庫版本</h3> +<p><a name="Updating_the_version_of_the_database"></a>新版本資料庫建立會觸發onupgradeneeded事件，在這個事件的處理器中要建立這個版本資料庫需要的物件存檔。</p> +<pre class="brush:js;">// This event is only implemented in recent browsers +request.onupgradeneeded = function(event) { + var db = event.target.result; + + // Create an objectStore for this database + var objectStore = db.createObjectStore("name", { keyPath: "myKey" }); +};</pre> +<p>資料庫版本是unsigned long long的數字，所以能夠非常長。</p> +<div class="warning"> + <p>請注意這也意味著版本不能為浮點數，否則小數點部分將會無條件捨去，而交易也可能不會開始，upgradeneeded事件也不會觸發。不要像以下例子以2.4作版本:</p> + <pre class="brush: js">var request = indexedDB.open("MyTestDatabase", 2.4); // don't do this, as the version will be rounded to 2</pre> +</div> +<p>升級版本資料庫建立會觸發onupgradeneeded事件，這個時候資料庫裡面已經含有前版本下的物件存檔，所以說不需要再次建立這些物件存檔了，剩下的是新增或刪除物件存檔。如果想要更動既存物件存檔(例如改變資料鍵路徑)，那麼會需要先刪除舊的再產生一個新的(請注意這也會刪除物件存檔裡的資料，所以如果資料需要保留的話，請在升級前先讀出資料備份。)</p> +<p>Webkit支援最新標準不過只有Chrome 23才開始導入，而較舊不支援最新版標準的版本則不支援indexedDB.open(name, version).onupgradeneeded。關於如何在舊版標準下升級資料庫版本請參考<a href="https://developer.mozilla.org/en-US/docs/Web/API/IDBDatabase?redirectlocale=en-US&redirectslug=IndexedDB%2FIDBDatabase#setVersion%28%29_.0A.0ADeprecated">"IDBDatabase參考文章"</a>。</p> +<h3 id="結構化資料庫">結構化資料庫</h3> +<p>indexedDB不用資料表而是物件存檔，物件存檔可以有很多。一筆物件存檔裡的資料值對應一筆資料鍵，依據使用{資料鍵路徑(<a href="/en/IndexedDB#gloss_key_path" title="https://developer.mozilla.org/en/IndexedDB#gloss_key_path">key path</a>)}或{資料鍵產生器(<a href="/en/IndexedDB#gloss_key_generator" title="en/IndexedDB#gloss key generator">key generator</a>)}。</p> +<p>下表列出資料建各類產生途徑:</p> +<table class="standard-table" style=""> + <thead> + <tr> + <th scope="col">Key Path</th> + <th scope="col">Key Generator</th> + <th scope="col">描述</th> + </tr> + </thead> + <tbody> + <tr> + <td>No</td> + <td>No</td> + <td>物件存檔資料值能為任何型別，即使像數字或字串。每當新增一筆資料，必須提供不同的資料鍵。</td> + </tr> + <tr> + <td>Yes</td> + <td>No</td> + <td>物件存檔資料值僅能為Javacript物件，而該資料物件必須含有和資料鍵路徑相同名稱之屬性成員。</td> + </tr> + <tr> + <td>No</td> + <td>Yes</td> + <td>物件存檔資料值能為任何型別，資料鍵自動產生，但如果想要指定資料鍵也可以另外提供資料鍵。</td> + </tr> + <tr> + <td>Yes</td> + <td>Yes</td> + <td>物件存檔資料值僅能為Javascript物件。通常被產生的新資料鍵的值會被存在物件屬性名稱和資料鍵路徑名稱相同的物件屬性下，如果這個屬性已經存在，這個已經存在之屬性之值將被用作為資料鍵，而非新產生的資料鍵。</td> + </tr> + </tbody> +</table> +<p>我們可以替任何儲存資料為物件型態而非原始資料型態的物件存檔建立索引，索引讓我們能夠用物件存檔中資料物件內的某一個屬性值查找資料，而非僅僅物件的資料鍵。</p> +<p>除此之外，利用索引還可以施加簡單的儲存限制；建立索引時設定獨特旗標(flag)，這個索引保證在此索引資料鍵下不會存在兩個物件存檔擁有同樣資料值，比如說現在有一個存放許多使用者的物件存檔，而且我們希望保證不會存在有兩個使用者的電子郵件地址一樣，此使索引的獨特旗標便可以幫助我們達成目標。</p> +<p>以上聽起來可能會有些複雜，請看一下下面的實例:</p> +<pre class="brush: js">// This is what our customer data looks like. +const customerData = [ + { ssn: "444-44-4444", name: "Bill", age: 35, email: "bill@company.com" }, + { ssn: "555-55-5555", name: "Donna", age: 32, email: "donna@home.org" } +]; +const dbName = "the_name"; + +var request = indexedDB.open(dbName, 2); + +request.onerror = function(event) { + // Handle errors. +}; +request.onupgradeneeded = function(event) { + var db = event.target.result; + + // Create an objectStore to hold information about our customers. We're + // going to use "ssn" as our key path because it's guaranteed to be + // unique. + var objectStore = db.createObjectStore("customers", { keyPath: "ssn" }); + + // Create an index to search customers by name. We may have duplicates + // so we can't use a unique index. + objectStore.createIndex("name", "name", { unique: false }); + + // Create an index to search customers by email. We want to ensure that + // no two customers have the same email, so use a unique index. + objectStore.createIndex("email", "email", { unique: true }); + + // Store values in the newly created objectStore. + for (var i in customerData) { + objectStore.add(customerData[i]); + } +}; +</pre> +<p>請注意onupgradeneeded事件是唯一能夠變更資料庫結構之處，在此事件才能建立或刪除物件存檔以及建立和刪除索引。</p> +<div> + 呼叫<a href="https://developer.mozilla.org/en-US/docs/Web/API/IDBDatabase?redirectlocale=en-US&redirectslug=IndexedDB%2FIDBDatabase#setVersion%28%29_.0A.0ADeprecated">IDBDatabase</a>類別物件的createObjectStore方法會立刻創造一個物件存檔，這個方法接收兩個參數，一個是物件存檔名稱，一個是非必填的參數物件，雖然參數物件不為必填但是卻相當重要，因為它讓我們定義了一些重要屬性(請參考<a href="https://developer.mozilla.org/en-US/docs/Web/API/IDBDatabase?redirectlocale=en-US&redirectslug=IndexedDB%2FIDBDatabase#createObjectStore">createObjectStore</a>)。本例中我們要求建立了一個"customer"物件存檔，定義"ssn"屬性為資料件路徑，使用"ssn"作為資料鍵路徑是因為每個客戶的ssn碼一定是獨立的。一旦決定了"ssn"作為資料鍵路徑，那麼每一筆資料一定要含有"ssn"。</div> +<p>本例還創建一個稱為"name"的索引，"name"索引查找目標為資料的"name"屬性，且不設立其獨特旗標(unique為false)，同樣地，我們又呼叫<a href="https://developer.mozilla.org/en-US/docs/Web/API/IDBObjectStore?redirectlocale=en-US&redirectslug=IndexedDB%2FIDBObjectStore#createIndex()">createIndex</a>方法創建了一個"email"索引，不過"email"索引具備獨特旗標(unique為true)。雖然存在"name"索引，但資料不一定要含有"name"屬性，只是當搜索"name"索引時資料不會出現。</p> +<p>接下來我們可以開始用ssn從物件存檔中取出資料，或是用索引找出資料(請參考<a href="https://developer.mozilla.org/zh-TW/docs/IndexedDB/Using_IndexedDB#.E4.BD.BF.E7.94.A8.E7.B4.A2.E5.BC.95">使用索引</a>)。</p> +<h3 id="使用資料鍵產生器">使用資料鍵產生器</h3> +<p>當建立物件存檔時設定autoIncrement旗標為ture將啟動資料鍵產生器，預設上該旗標為false。</p> +<p>有了資料鍵產生器，當新增資料到物件存檔中，資料鍵產生器會自動幫我們產生資料鍵。資料鍵產生器產生的資料鍵由整數1開始，而基本上新產生的資料鍵是由前一個資料鍵加1產生。資料鍵的產生不會因為資料刪除或清空所有資料而重新開始起算，所以資料鍵值是一直累加上去的，除非資料庫操作中斷，整個交易作業被取消。</p> +<p>我們可以建立一個有資料鍵產生器的物件存檔如下:</p> +<pre class="brush: js">// Open the indexedDB. +var request = indexedDB.open(dbName, 3); + +request.onupgradeneeded = function (event) { + var db = event.target.result; + + // Create another object store called "names" with the autoIncrement flag set as true. + var objStore = db.createObjectStore("names", { autoIncrement : true }); + + // Because the "names" object store has the key generator, the key for the name value is generated automatically. + // The added records would be like: + // key : 1 => value : "Bill" + // key : 2 => value : "Donna" + for (var i in customerData) { + objStore.add(customerData[i].name); + } +}</pre> +<p>關於資料鍵產生器細節，請參考<a href="http://www.w3.org/TR/IndexedDB/#key-generator-concept">"W3C Key Generators"</a>。</p> +<h2 id="新增和刪除資料">新增和刪除資料</h2> +<p>在操作資料庫之前必須要先進行交易，交易來自資料庫物件，在交易中要指定涵蓋物件存檔範圍，然後也要決定是要變更資料庫或純粹讀取資料。交易共有三種種類，分別是讀取(read-only)，讀寫(read/write), 以及版本變更(versionchange)，如果只需要讀資料最好只使用讀取(read-only)交易，因為讀取(read-only)交易可以多重同步進行。</p> +<h3 id="新增資料到資料庫">新增資料到資料庫</h3> +<p>創建資料庫後，如果要寫入資料請這麼做:</p> +<pre class="brush:js;">var transaction = db.transaction(["customers"], "readwrite"); +// Note: Older experimental implementations use the deprecated constant IDBTransaction.READ_WRITE instead of "readwrite". +// In case you want to support such an implementation, you can just write: +// var transaction = db.transaction(["customers"], IDBTransaction.READ_WRITE);</pre> +<p>呼叫<a href="https://developer.mozilla.org/en-US/docs/Web/API/IDBDatabase#transaction">transaction()</a>方法會回傳一個交易物件。transaction()第一個接受參數代表交易涵蓋的物件存檔，雖然傳入空陣列會讓交易涵蓋所有物件存檔，但請不要這麼做，因為根據正式標準傳入空陣列應該要導致InvalidAccessError錯誤；第二個參數代表交易種類，不傳入的話預設為讀取交易，本例要寫入資料庫所以傳入讀寫("readwrite")。</p> +<p>交易的生命週期和事件循環關係密切。當我們發起交易又回到事件循環中後，如果忽略，那麼交易將轉成結束，唯一保持交易存活的方法是在交易上發出請求；當請求完成後我們會收到DOM事件，假設請求結果成功，我們可以在事件的回呼函數(callback中)繼續進行交易，反之，如果我們沒有繼續進行交易，那麼交易將結束，也就是說只要尚有未完成請求的話，交易就會繼續存活，如果收到TRANSACTION_INACTIVE_ERR錯誤那便意謂著交易早已結束，我們錯過了繼續進行交易的機會。</p> +<p>交易能收到三種事件: 錯誤(error)、中斷(abort)以及完成(complete)，其中錯誤事件會向上傳遞，所以任何一個交易下轄的請求產生錯誤事件，該交易都會收到。如果交易收到錯誤事件時，瀏覽器預設行為會中斷交易，除非我們有在錯誤事件上呼叫preventDefault()阻擋瀏覽器預設行動，否則整筆交易都將取消、復原，這樣的設計告訴我們必須要思考如何處裡錯誤，或者說如果對每一個錯誤進行處裡過於麻煩，那麼至少加入一個概括性的錯誤處理器也是可以。只要不處裡錯誤或呼叫abort()，交易將取消、復原，然後中斷事件接著觸發，反之，當所有請求都完成後，我們會收到一個完成事件，所以說如果我們同時發起多項請求時，可以只追蹤單一交易而非個別請求，這樣會大大減輕我們的負擔。</p> +<p>有了交易之後便能夠從中取得物件存檔，有了物件存檔便能夠新增資料(請注意唯有在建立交易時指定的物件存檔能夠取得)。</p> +<pre class="brush: js">// Do something when all the data is added to the database. +transaction.oncomplete = function(event) { + alert("All done!"); +}; + +transaction.onerror = function(event) { + // Don't forget to handle errors! +}; + +var objectStore = transaction.objectStore("customers"); +for (var i in customerData) { + var request = objectStore.add(customerData[i]); + request.onsuccess = function(event) { + // event.target.result == customerData[i].ssn; + }; +}</pre> +<p>呼叫<a href="https://developer.mozilla.org/en-US/docs/Web/API/IDBObjectStore#add()">add</a>方法可以加入一筆新資料，呼叫後會回傳一個<a href="https://developer.mozilla.org/en-US/docs/Web/API/IDBRequest?redirectlocale=en-US&redirectslug=IndexedDB%2FIDBRequest">IDBRequest</a>物件，即為上方範例中的request，如果新增成功，request的成功事件會被觸發，而成功事件物件中有一個result屬性，這個result值剛好就等於新資料的資料鍵，所以說上方範例中的event.target.result剛好就等於顧客的ssn值(因為我們用ssn屬性作為資料鍵路徑)。請注意add方法只在當物件存檔中沒有相同資料鍵資料存在時有用，如果想要更動或是直接覆蓋現存資料請呼叫<a href="https://developer.mozilla.org/en-US/docs/Web/API/IDBObjectStore#put()">put</a>方法。</p> +<h2 id="移除資料">移除資料</h2> +<p>移除資料十分容易:</p> +<pre class="brush: js">var request = db.transaction(["customers"], "readwrite") + .objectStore("customers") + .delete("444-44-4444"); +request.onsuccess = function(event) { + // It's gone! +};</pre> +<h2 id="讀取資料">讀取資料</h2> +<p>要圖取資料庫內的資料有數種途徑，第一個最簡單的途徑就是提供資料鍵，呼叫<a href="https://developer.mozilla.org/en-US/docs/Web/API/IDBObjectStore#get()">get</a>方法取得資料:</p> +<pre class="brush: js">var transaction = db.transaction(["customers"]); +var objectStore = transaction.objectStore("customers"); +var request = objectStore.get("444-44-4444"); +request.onerror = function(event) { + // Handle errors! +}; +request.onsuccess = function(event) { + // Do something with the request.result! + alert("Name for SSN 444-44-4444 is " + request.result.name); +};</pre> +<p>假設我們把錯誤處理放在資料庫層級，我們可以再縮短上面的程式碼如下:</p> +<pre class="brush: js">db.transaction("customers").objectStore("customers").get("444-44-4444").onsuccess = function(event) { + alert("Name for SSN 444-44-4444 is " + event.target.result.name); +};</pre> +<p>呼叫transcation方法而不指定模式會開啟讀取(readonly)模式，接著取得我們的目標物件存檔，輸入目標資料的資料鍵，呼叫get方法取得請求物件，然後在請求物件上註冊成功事件處理器，當作業成功後，成功事件會觸發，成功事件的物件中含有請求物件(event.target如上述範例)，請求物件中含有請求結果(event.target.result如上述範例)。</p> +<h2 id="使用指標(Cursor)">使用指標(Cursor)</h2> +<p>使用get方法需要知道資料鍵，如果想要一一存取物件存檔中的資料，我們可以利用指標:</p> +<pre class="brush: js">var objectStore = db.transaction("customers").objectStore("customers"); + +objectStore.openCursor().onsuccess = function(event) { + var cursor = event.target.result; + if (cursor) { + alert("Name for SSN " + cursor.key + " is " + cursor.value.name); + cursor.continue(); + } + else { + alert("No more entries!"); + } +};</pre> +<p><a href="https://developer.mozilla.org/en-US/docs/Web/API/IDBObjectStore#openCursor()">openCursor</a>方法第一個參數用來接受資料鍵範圍物件來限制存取資料範圍，第二個參數用來指定存取進行方向，像上面的範例程式便是以資料鍵由小到大之方向存取資料；呼叫openCursor方法後一樣會回傳一個請求物件，成功時成功事件會觸發，不過這裡有些地方要特別注意，當成功事件處裡函數被喚起時，指標物件(cursor)會存放在result屬性內(亦即上述event.target.result)，cursor物件下有兩個屬性，key屬性是資料鍵，value屬性是資料值，如果要取得下一份資料就呼叫cursor的continue()方法，然後cursor物件就會指向下一份資料，當沒有資料時，cursor會是undefined，當請求一開始便找沒有資料，result屬性也會是undefined。</p> +<p>以下用cursor存取一遍資料後放在陣列中的作法相當常見:</p> +<pre class="brush: js">var customers = []; + +objectStore.openCursor().onsuccess = function(event) { + var cursor = event.target.result; + if (cursor) { + customers.push(cursor.value); + cursor.continue(); + } + else { + alert("Got all customers: " + customers); + } +};</pre> +<div class="warning"> + <strong>Warning:</strong> 以下範例不是IndexedDB標準!</div> +<p>Mozilla瀏覽器自己做了一個getAll()方法來方便一次取得所有cursor下的資料值，這個方法相當方便，不過請小心未來它有可能會消失。以下程式碼的效果和上面的一樣:</p> +<pre class="brush: js">objectStore.getAll().onsuccess = function(event) { + alert("Got all customers: " + event.target.result); +};</pre> +<p>一一檢查cursor的value屬性較不利性能表現，因為物件是被動一一建立，然而呼叫getAll()，Gecko一定要一次建立所有物件，所以如果想要一次取得所有物件的資料值陣列使用getAll()比較好，如果想要一一檢查每筆資料則請利用cursor的方法。</p> +<h3 id="使用索引">使用索引</h3> +<p>利用一定唯一的ssn碼作為資料鍵相當合乎邏輯(隱私權的問題先擱置一放，不在本文探討範圍)。不過當我們想要查詢使用者的名字的時候，如果沒有索引就需要一一檢查每一筆資料，十分沒有效率，所以我們可以建立name的索引。</p> +<pre class="brush: js">var index = objectStore.index("name"); +index.get("Donna").onsuccess = function(event) { + alert("Donna's SSN is " + event.target.result.ssn); +};</pre> +<p>因為name不是唯一值，所以可能會有多筆資料符合"Donna"名字，此時呼叫get()會取得資料鍵最小值的資料。</p> +<p>如果我們想要查看特定名字下所有的資料，可以利用cursor。有兩種cursor能用在索引上，第一種一般cursor會比對索引值並回傳整份資料(物件存檔中的物件)，第二種資料鍵cursor則只會回傳資料鍵值，請參考下方範例比較兩者差異:</p> +<pre class="brush: js">index.openCursor().onsuccess = function(event) { + var cursor = event.target.result; + if (cursor) { + // cursor.key is a name, like "Bill", and cursor.value is the whole object. + alert("Name: " + cursor.key + ", SSN: " + cursor.value.ssn + ", email: " + cursor.value.email); + cursor.continue(); + } +}; + +index.openKeyCursor().onsuccess = function(event) { + var cursor = event.target.result; + if (cursor) { + // cursor.key is a name, like "Bill", and cursor.value is the SSN. + // No way to directly get the rest of the stored object. + alert("Name: " + cursor.key + ", SSN: " + cursor.value); + cursor.continue(); + } +};</pre> +<h3 id="設定指標查詢範圍和方向">設定指標查詢範圍和方向</h3> +<p>如果想要限定指標查詢範圍，那麼在乎叫openCursor()或openKeyCursor()時第一個參數要傳入<a href="https://developer.mozilla.org/en/IndexedDB/IDBKeyRange">IDBKeyRange</a>物件以限制範圍。IDBKeyRange物件能夠只聚焦在單一資料鍵上或者一段上下限區間；上下限區間可以是封閉(含界限)或開放(不含界限)，請看以下範例:</p> +<pre class="brush: js">// Only match "Donna" +var singleKeyRange = IDBKeyRange.only("Donna"); + +// Match anything past "Bill", including "Bill" +var lowerBoundKeyRange = IDBKeyRange.lowerBound("Bill"); + +// Match anything past "Bill", but don't include "Bill" +var lowerBoundOpenKeyRange = IDBKeyRange.lowerBound("Bill", true); + +// Match anything up to, but not including, "Donna" +var upperBoundOpenKeyRange = IDBKeyRange.upperBound("Donna", true); + +// Match anything between "Bill" and "Donna", but not including "Donna" +var boundKeyRange = IDBKeyRange.bound("Bill", "Donna", false, true); + +index.openCursor(boundKeyRange).onsuccess = function(event) { + var cursor = event.target.result; + if (cursor) { + // Do something with the matches. + cursor.continue(); + } +};</pre> +<p>有時候我們會想要由大到小查看資料而非預設由小到大方向，傳入第二個"prev"字串便能做到:</p> +<pre class="brush: js">objectStore.openCursor(null, "prev").onsuccess = function(event) { + var cursor = event.target.result; + if (cursor) { + // Do something with the entries. + cursor.continue(); + } +};</pre> +<p>由於"name"索引不具唯一性，所以一個名字下可能會出現多筆資料，此時如果想要避開這多筆資料，請傳入"nextunique"或"prevunique"做為第二個方向參數，當傳入之後，如一個名字下遇到多筆資料，則只有資料鍵最小的資料會被回傳。</p> +<pre class="brush: js">index.openKeyCursor(null, "nextunique").onsuccess = function(event) { + var cursor = event.target.result; + if (cursor) { + // Do something with the entries. + cursor.continue(); + } +};</pre> +<p>關於可傳入的方向參數，請參考<a href="https://developer.mozilla.org/en-US/docs/Web/API/IDBCursor?redirectlocale=en-US&redirectslug=IndexedDB%2FIDBCursor#Constants">IDBCursor</a>常數。</p> +<h2 id="當網頁應用程式於瀏覽器另一個分頁開啟時變更版本">當網頁應用程式於瀏覽器另一個分頁開啟時變更版本</h2> +<p>請思考以下狀況: 使用者在第一個瀏覽器分頁中使用著舊版本，然後使用者又打開第二個分頁載入網頁，此時我們在新分頁需要對資料庫進行升級，所以呼叫open()以更新版本開啟資料庫，但是由於第一個瀏覽器分頁並沒有關閉資料庫，因此第二個分頁的資料庫升級作業會被擋住。所以我們需要注意多個分頁同時開啟的狀況，每個分頁都得注意當發生資料庫升級事件時，要記得關閉資料庫，讓資料庫升級作業得以進行。實際作法如下:</p> +<pre class="brush: js">var openReq = mozIndexedDB.open("MyTestDatabase", 2); + +openReq.onblocked = function(event) { + // If some other tab is loaded with the database, then it needs to be closed + // before we can proceed. + alert("Please close all other tabs with this site open!"); +}; + +openReq.onupgradeneeded = function(event) { + // All other databases have been closed. Set everything up. + db.createObjectStore(/* ... */); + useDatabase(db); +} + +openReq.onsuccess = function(event) { + var db = event.target.result; + useDatabase(db); + return; +} + +function useDatabase(db) { + // Make sure to add a handler to be notified if another page requests a version + // change. We must close the database. This allows the other page to upgrade the database. + // If you don't do this then the upgrade won't happen until the user closes the tab. + db.onversionchange = function(event) { + db.close(); + alert("A new version of this page is ready. Please reload!"); + }; + + // Do stuff with the database. +} +</pre> +<h2 id="安全性">安全性</h2> +<p>IndexedDB遵守<a href="https://developer.mozilla.org/zh-TW/docs/Web/JavaScript/Same_origin_policy_for_JavaScript">同源政策</a>，所以它綁定創建它的來源網站，其他來源網站無法存取。<br> + 就像對載入{{ HTMLElement("frame") }}和{{ HTMLElement("iframe") }}網頁的第三方cookie所設下的安全性和隱私權考量限制，IndexedDB無法在載入{{ HTMLElement("frame") }}和{{ HTMLElement("iframe") }}網頁上運作，詳情請見{{ bug(595307) }}。</p> +<h2 id="瀏覽器關閉風險">瀏覽器關閉風險</h2> +<p>當瀏覽器關閉，例如使用者按下關閉鈕，任何未完成IndexedDB交易都將默默中止，這些交易不會完成，錯誤事件也不會觸發。既然瀏覽器可能隨時被關閉，我們無法完全指望任何特定交易一定會完成，或是依賴錯誤事件做出相應處理，針對這種狀況，我們需要注意:</p> +<p>第一、每一筆交易結束後都應該要保持資料庫完整性，例如說，有一串使用者編輯項目清單正要存入資料庫，我們如果先在一個交易中清除舊清單，然後在另一個交易中存入新清單，那就會面臨到清除完就清單後，新清單存入交易還來不及回存，瀏覽器就關閉的風險，而這個時候資料庫裡面的清單資料將消失。所以比較好的做法應該是在同一筆交易中完成清除舊清單和存入新清單。</p> +<p>第二、永遠不要在unload事件中執行資料庫交易，因為如果unload事件是觸發在瀏覽器關閉下，任何資料庫交易都不會發生，或許，瀏覽器(或分頁)打開時讀取資料庫，更新資料庫當使用者編輯資料，當瀏覽器(或分頁)關閉時儲存資料這樣的做法比較直覺，不過資料庫的操作是非同步進行地，所以瀏覽器關閉的執行會在資料庫操作前發生，進而中斷後續非同步的資料庫交易，所以在unload事件中執行資料庫交易是行不通地。</p> +<p>事實上不論瀏覽器是否正常關閉，都沒有任何方法保證IndexedDB交易能夠順利完成，請見{{ bug(870645) }}。</p> +<h2 id="Full_IndexedDB_example" name="Full_IndexedDB_example">完整IndexedDB範例</h2> +<h3 id="HTML">HTML</h3> +<pre class="brush: html"><script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js"></script> + + <h1>IndexedDB Demo: storing blobs, e-publication example</h1> + <div class="note"> + <p> + Works and tested with: + </p> + <div id="compat"> + </div> + </div> + + <div id="msg"> + </div> + + <form id="register-form"> + <table> + <tbody> + <tr> + <td> + <label for="pub-title" class="required"> + Title: + </label> + </td> + <td> + <input type="text" id="pub-title" name="pub-title" /> + </td> + </tr> + <tr> + <td> + <label for="pub-biblioid" class="required"> + Bibliographic ID:<br/> + <span class="note">(ISBN, ISSN, etc.)</span> + </label> + </td> + <td> + <input type="text" id="pub-biblioid" name="pub-biblioid"/> + </td> + </tr> + <tr> + <td> + <label for="pub-year"> + Year: + </label> + </td> + <td> + <input type="number" id="pub-year" name="pub-year" /> + </td> + </tr> + </tbody> + <tbody> + <tr> + <td> + <label for="pub-file"> + File image: + </label> + </td> + <td> + <input type="file" id="pub-file"/> + </td> + </tr> + <tr> + <td> + <label for="pub-file-url"> + Online-file image URL:<br/> + <span class="note">(same origin URL)</span> + </label> + </td> + <td> + <input type="text" id="pub-file-url" name="pub-file-url"/> + </td> + </tr> + </tbody> + </table> + + <div class="button-pane"> + <input type="button" id="add-button" value="Add Publication" /> + <input type="reset" id="register-form-reset"/> + </div> + </form> + + <form id="delete-form"> + <table> + <tbody> + <tr> + <td> + <label for="pub-biblioid-to-delete"> + Bibliographic ID:<br/> + <span class="note">(ISBN, ISSN, etc.)</span> + </label> + </td> + <td> + <input type="text" id="pub-biblioid-to-delete" + name="pub-biblioid-to-delete" /> + </td> + </tr> + <tr> + <td> + <label for="key-to-delete"> + Key:<br/> + <span class="note">(for example 1, 2, 3, etc.)</span> + </label> + </td> + <td> + <input type="text" id="key-to-delete" + name="key-to-delete" /> + </td> + </tr> + </tbody> + </table> + <div class="button-pane"> + <input type="button" id="delete-button" value="Delete Publication" /> + <input type="button" id="clear-store-button" + value="Clear the whole store" class="destructive" /> + </div> + </form> + + <form id="search-form"> + <div class="button-pane"> + <input type="button" id="search-list-button" + value="List database content" /> + </div> + </form> + + <div> + <div id="pub-msg"> + </div> + <div id="pub-viewer"> + </div> + <ul id="pub-list"> + </ul> + </div> +</pre> +<h3 id="CSS">CSS</h3> +<pre class="brush: css">body { + font-size: 0.8em; + font-family: Sans-Serif; +} + +form { + background-color: #cccccc; + border-radius: 0.3em; + display: inline-block; + margin-bottom: 0.5em; + padding: 1em; +} + +table { + border-collapse: collapse; +} + +input { + padding: 0.3em; + border-color: #cccccc; + border-radius: 0.3em; +} + +.required:after { + content: "*"; + color: red; +} + +.button-pane { + margin-top: 1em; +} + +#pub-viewer { + float: right; + width: 48%; + height: 20em; + border: solid #d092ff 0.1em; +} +#pub-viewer iframe { + width: 100%; + height: 100%; +} + +#pub-list { + width: 46%; + background-color: #eeeeee; + border-radius: 0.3em; +} +#pub-list li { + padding-top: 0.5em; + padding-bottom: 0.5em; + padding-right: 0.5em; +} + +#msg { + margin-bottom: 1em; +} + +.action-success { + padding: 0.5em; + color: #00d21e; + background-color: #eeeeee; + border-radius: 0.2em; +} + +.action-failure { + padding: 0.5em; + color: #ff1408; + background-color: #eeeeee; + border-radius: 0.2em; +} + +.note { + font-size: smaller; +} + +.destructive { + background-color: orange; +} +.destructive:hover { + background-color: #ff8000; +} +.destructive:active { + background-color: red; +} +</pre> +<p> </p> +<h3 id="JavaScript">JavaScript</h3> +<pre class="brush: js">(function () { + var COMPAT_ENVS = [ + ['Firefox', ">= 16.0"], + ['Google Chrome', + ">= 24.0 (you may need to get Google Chrome Canary), NO Blob storage support"] + ]; + var compat = $('#compat'); + compat.empty(); + compat.append('<ul id="compat-list"></ul>'); + COMPAT_ENVS.forEach(function(val, idx, array) { + $('#compat-list').append('<li>' + val[0] + ': ' + val[1] + '</li>'); + }); + + const DB_NAME = 'mdn-demo-indexeddb-epublications'; + const DB_VERSION = 1; // Use a long long for this value (don't use a float) + const DB_STORE_NAME = 'publications'; + + var db; + + // Used to keep track of which view is displayed to avoid uselessly reloading it + var current_view_pub_key; + + function openDb() { + console.log("openDb ..."); + var req = indexedDB.open(DB_NAME, DB_VERSION); + req.onsuccess = function (evt) { + // Better use "this" than "req" to get the result to avoid problems with + // garbage collection. + // db = req.result; + db = this.result; + console.log("openDb DONE"); + }; + req.onerror = function (evt) { + console.error("openDb:", evt.target.errorCode); + }; + + req.onupgradeneeded = function (evt) { + console.log("openDb.onupgradeneeded"); + var store = evt.currentTarget.result.createObjectStore( + DB_STORE_NAME, { keyPath: 'id', autoIncrement: true }); + + store.createIndex('biblioid', 'biblioid', { unique: true }); + store.createIndex('title', 'title', { unique: false }); + store.createIndex('year', 'year', { unique: false }); + }; + } + + /** + * @param {string} store_name + * @param {string} mode either "readonly" or "readwrite" + */ + function getObjectStore(store_name, mode) { + var tx = db.transaction(store_name, mode); + return tx.objectStore(store_name); + } + + function clearObjectStore(store_name) { + var store = getObjectStore(DB_STORE_NAME, 'readwrite'); + var req = store.clear(); + req.onsuccess = function(evt) { + displayActionSuccess("Store cleared"); + displayPubList(store); + }; + req.onerror = function (evt) { + console.error("clearObjectStore:", evt.target.errorCode); + displayActionFailure(this.error); + }; + } + + function getBlob(key, store, success_callback) { + var req = store.get(key); + req.onsuccess = function(evt) { + var value = evt.target.result; + if (value) + success_callback(value.blob); + }; + } + + /** + * @param {IDBObjectStore=} store + */ + function displayPubList(store) { + console.log("displayPubList"); + + if (typeof store == 'undefined') + store = getObjectStore(DB_STORE_NAME, 'readonly'); + + var pub_msg = $('#pub-msg'); + pub_msg.empty(); + var pub_list = $('#pub-list'); + pub_list.empty(); + // Resetting the iframe so that it doesn't display previous content + newViewerFrame(); + + var req; + req = store.count(); + // Requests are executed in the order in which they were made against the + // transaction, and their results are returned in the same order. + // Thus the count text below will be displayed before the actual pub list + // (not that it is algorithmically important in this case). + req.onsuccess = function(evt) { + pub_msg.append('<p>There are <strong>' + evt.target.result + + '</strong> record(s) in the object store.</p>'); + }; + req.onerror = function(evt) { + console.error("add error", this.error); + displayActionFailure(this.error); + }; + + var i = 0; + req = store.openCursor(); + req.onsuccess = function(evt) { + var cursor = evt.target.result; + + // If the cursor is pointing at something, ask for the data + if (cursor) { + console.log("displayPubList cursor:", cursor); + req = store.get(cursor.key); + req.onsuccess = function (evt) { + var value = evt.target.result; + var list_item = $('<li>' + + '[' + cursor.key + '] ' + + '(biblioid: ' + value.biblioid + ') ' + + value.title + + '</li>'); + if (value.year != null) + list_item.append(' - ' + value.year); + + if (value.hasOwnProperty('blob') && + typeof value.blob != 'undefined') { + var link = $('<a href="' + cursor.key + '">File</a>'); + link.on('click', function() { return false; }); + link.on('mouseenter', function(evt) { + setInViewer(evt.target.getAttribute('href')); }); + list_item.append(' / '); + list_item.append(link); + } else { + list_item.append(" / No attached file"); + } + pub_list.append(list_item); + }; + + // Move on to the next object in store + cursor.continue(); + + // This counter serves only to create distinct ids + i++; + } else { + console.log("No more entries"); + } + }; + } + + function newViewerFrame() { + var viewer = $('#pub-viewer'); + viewer.empty(); + var iframe = $('<iframe />'); + viewer.append(iframe); + return iframe; + } + + function setInViewer(key) { + console.log("setInViewer:", arguments); + key = Number(key); + if (key == current_view_pub_key) + return; + + current_view_pub_key = key; + + var store = getObjectStore(DB_STORE_NAME, 'readonly'); + getBlob(key, store, function(blob) { + console.log("setInViewer blob:", blob); + var iframe = newViewerFrame(); + + // It is not possible to set a direct link to the + // blob to provide a mean to directly download it. + if (blob.type == 'text/html') { + var reader = new FileReader(); + reader.onload = (function(evt) { + var html = evt.target.result; + iframe.load(function() { + $(this).contents().find('html').html(html); + }); + }); + reader.readAsText(blob); + } else if (blob.type.indexOf('image/') == 0) { + iframe.load(function() { + var img_id = 'image-' + key; + var img = $('<img id="' + img_id + '"/>'); + $(this).contents().find('body').html(img); + var obj_url = window.URL.createObjectURL(blob); + $(this).contents().find('#' + img_id).attr('src', obj_url); + window.URL.revokeObjectURL(obj_url); + }); + } else if (blob.type == 'application/pdf') { + $('*').css('cursor', 'wait'); + var obj_url = window.URL.createObjectURL(blob); + iframe.load(function() { + $('*').css('cursor', 'auto'); + }); + iframe.attr('src', obj_url); + window.URL.revokeObjectURL(obj_url); + } else { + iframe.load(function() { + $(this).contents().find('body').html("No view available"); + }); + } + + }); + } + + /** + * @param {string} biblioid + * @param {string} title + * @param {number} year + * @param {string} url the URL of the image to download and store in the local + * IndexedDB database. The resource behind this URL is subjected to the + * "Same origin policy", thus for this method to work, the URL must come from + * the same origin as the web site/app this code is deployed on. + */ + function addPublicationFromUrl(biblioid, title, year, url) { + console.log("addPublicationFromUrl:", arguments); + + var xhr = new XMLHttpRequest(); + xhr.open('GET', url, true); + // Setting the wanted responseType to "blob" + // http://www.w3.org/TR/XMLHttpRequest2/#the-response-attribute + xhr.responseType = 'blob'; + xhr.onload = function (evt) { + if (xhr.status == 200) { + console.log("Blob retrieved"); + var blob = xhr.response; + console.log("Blob:", blob); + addPublication(biblioid, title, year, blob); + } else { + console.error("addPublicationFromUrl error:", + xhr.responseText, xhr.status); + } + }; + xhr.send(); + + // We can't use jQuery here because as of jQuery 1.8.3 the new "blob" + // responseType is not handled. + // http://bugs.jquery.com/ticket/11461 + // http://bugs.jquery.com/ticket/7248 + // $.ajax({ + // url: url, + // type: 'GET', + // xhrFields: { responseType: 'blob' }, + // success: function(data, textStatus, jqXHR) { + // console.log("Blob retrieved"); + // console.log("Blob:", data); + // // addPublication(biblioid, title, year, data); + // }, + // error: function(jqXHR, textStatus, errorThrown) { + // console.error(errorThrown); + // displayActionFailure("Error during blob retrieval"); + // } + // }); + } + + /** + * @param {string} biblioid + * @param {string} title + * @param {number} year + * @param {Blob=} blob + */ + function addPublication(biblioid, title, year, blob) { + console.log("addPublication arguments:", arguments); + var obj = { biblioid: biblioid, title: title, year: year }; + if (typeof blob != 'undefined') + obj.blob = blob; + + var store = getObjectStore(DB_STORE_NAME, 'readwrite'); + var req; + try { + req = store.add(obj); + } catch (e) { + if (e.name == 'DataCloneError') + displayActionFailure("This engine doesn't know how to clone a Blob, " + + "use Firefox"); + throw e; + } + req.onsuccess = function (evt) { + console.log("Insertion in DB successful"); + displayActionSuccess(); + displayPubList(store); + }; + req.onerror = function() { + console.error("addPublication error", this.error); + displayActionFailure(this.error); + }; + } + + /** + * @param {string} biblioid + */ + function deletePublicationFromBib(biblioid) { + console.log("deletePublication:", arguments); + var store = getObjectStore(DB_STORE_NAME, 'readwrite'); + var req = store.index('biblioid'); + req.get(biblioid).onsuccess = function(evt) { + if (typeof evt.target.result == 'undefined') { + displayActionFailure("No matching record found"); + return; + } + deletePublication(evt.target.result.id, store); + }; + req.onerror = function (evt) { + console.error("deletePublicationFromBib:", evt.target.errorCode); + }; + } + + /** + * @param {number} key + * @param {IDBObjectStore=} store + */ + function deletePublication(key, store) { + console.log("deletePublication:", arguments); + + if (typeof store == 'undefined') + store = getObjectStore(DB_STORE_NAME, 'readwrite'); + + // As per spec http://www.w3.org/TR/IndexedDB/#object-store-deletion-operation + // the result of the Object Store Deletion Operation algorithm is + // undefined, so it's not possible to know if some records were actually + // deleted by looking at the request result. + var req = store.get(key); + req.onsuccess = function(evt) { + var record = evt.target.result; + console.log("record:", record); + if (typeof record == 'undefined') { + displayActionFailure("No matching record found"); + return; + } + // Warning: The exact same key used for creation needs to be passed for + // the deletion. If the key was a Number for creation, then it needs to + // be a Number for deletion. + req = store.delete(key); + req.onsuccess = function(evt) { + console.log("evt:", evt); + console.log("evt.target:", evt.target); + console.log("evt.target.result:", evt.target.result); + console.log("delete successful"); + displayActionSuccess("Deletion successful"); + displayPubList(store); + }; + req.onerror = function (evt) { + console.error("deletePublication:", evt.target.errorCode); + }; + }; + req.onerror = function (evt) { + console.error("deletePublication:", evt.target.errorCode); + }; + } + + function displayActionSuccess(msg) { + msg = typeof msg != 'undefined' ? "Success: " + msg : "Success"; + $('#msg').html('<span class="action-success">' + msg + '</span>'); + } + function displayActionFailure(msg) { + msg = typeof msg != 'undefined' ? "Failure: " + msg : "Failure"; + $('#msg').html('<span class="action-failure">' + msg + '</span>'); + } + function resetActionStatus() { + console.log("resetActionStatus ..."); + $('#msg').empty(); + console.log("resetActionStatus DONE"); + } + + function addEventListeners() { + console.log("addEventListeners"); + + $('#register-form-reset').click(function(evt) { + resetActionStatus(); + }); + + $('#add-button').click(function(evt) { + console.log("add ..."); + var title = $('#pub-title').val(); + var biblioid = $('#pub-biblioid').val(); + if (!title || !biblioid) { + displayActionFailure("Required field(s) missing"); + return; + } + var year = $('#pub-year').val(); + if (year != '') { + // Better use Number.isInteger if the engine has EcmaScript 6 + if (isNaN(year)) { + displayActionFailure("Invalid year"); + return; + } + year = Number(year); + } else { + year = null; + } + + var file_input = $('#pub-file'); + var selected_file = file_input.get(0).files[0]; + console.log("selected_file:", selected_file); + // Keeping a reference on how to reset the file input in the UI once we + // have its value, but instead of doing that we rather use a "reset" type + // input in the HTML form. + //file_input.val(null); + var file_url = $('#pub-file-url').val(); + if (selected_file) { + addPublication(biblioid, title, year, selected_file); + } else if (file_url) { + addPublicationFromUrl(biblioid, title, year, file_url); + } else { + addPublication(biblioid, title, year); + } + + }); + + $('#delete-button').click(function(evt) { + console.log("delete ..."); + var biblioid = $('#pub-biblioid-to-delete').val(); + var key = $('#key-to-delete').val(); + + if (biblioid != '') { + deletePublicationFromBib(biblioid); + } else if (key != '') { + // Better use Number.isInteger if the engine has EcmaScript 6 + if (key == '' || isNaN(key)) { + displayActionFailure("Invalid key"); + return; + } + key = Number(key); + deletePublication(key); + } + }); + + $('#clear-store-button').click(function(evt) { + clearObjectStore(); + }); + + var search_button = $('#search-list-button'); + search_button.click(function(evt) { + displayPubList(); + }); + + } + + openDb(); + addEventListeners(); + +})(); // Immediately-Invoked Function Expression (IIFE) +</pre> +<p>{{ LiveSampleLink('Full_IndexedDB_example', "線上範例") }}</p> +<h2 id="下一步">下一步</h2> +<p>請參考<a href="https://developer.mozilla.org/zh-TW/docs/IndexedDB">IndexedDB文件</a>，看看有甚麼IndexedDB API可供使用，實際試玩一下吧。</p> +<h2 id="延伸閱讀">延伸閱讀</h2> +<p>參照</p> +<ul> + <li><a href="/en/IndexedDB" title="https://developer.mozilla.org/en/IndexedDB">IndexedDB API Reference</a></li> + <li><a class="external" href="http://www.w3.org/TR/IndexedDB/" title="http://www.w3.org/TR/IndexedDB/">Indexed Database API Specification</a></li> + <li><a href="/en-US/docs/IndexedDB/Using_IndexedDB_in_chrome" title="/en-US/docs/IndexedDB/Using_IndexedDB_in_chrome">Using IndexedDB in chrome</a></li> +</ul> +<p>相關教學</p> +<ul> + <li><a class="external" href="http://www.html5rocks.com/tutorials/indexeddb/todo/" title="http://www.html5rocks.com/tutorials/indexeddb/todo/">A simple TODO list using HTML5 IndexedDB</a><span class="external">. </span><span class="external">{{ Note("請注意此教學範例用到的已經廢棄的<code>setVersion()方法。</code>") }}</span></li> + <li><a href="http://www.html5rocks.com/en/tutorials/indexeddb/uidatabinding/" title="http://www.html5rocks.com/en/tutorials/indexeddb/uidatabinding/">Databinding UI Elements with IndexedDB</a></li> +</ul> +<p>相關文章</p> +<ul> + <li><a class="external" href="http://msdn.microsoft.com/en-us/scriptjunkie/gg679063.aspx" title="http://msdn.microsoft.com/en-us/scriptjunkie/gg679063.aspx">IndexedDB — The Store in Your Browser</a></li> +</ul> +<p>Firefox</p> +<ul> + <li>Mozilla <a class="link-https" href="https://mxr.mozilla.org/mozilla-central/find?text=&string=dom%2FindexedDB%2F.*%5C.idl&regexp=1" title="https://mxr.mozilla.org/mozilla-central/find?text=&string=dom/indexedDB/.*\.idl&regexp=1">interface files</a></li> +</ul> diff --git a/files/zh-tw/web/api/keyboardevent/index.html b/files/zh-tw/web/api/keyboardevent/index.html new file mode 100644 index 0000000000..31d75cdf1f --- /dev/null +++ b/files/zh-tw/web/api/keyboardevent/index.html @@ -0,0 +1,449 @@ +--- +title: KeyboardEvent +slug: Web/API/KeyboardEvent +tags: + - 待翻譯 +translation_of: Web/API/KeyboardEvent +--- +<p>{{APIRef("DOM Events")}}</p> + +<p><strong><code>KeyboardEvent</code></strong> objects 用來詳述使用者和網頁之間，經由鍵盤產生的互動。每個事件（<code>event</code>）都記錄著一次鍵盤動作。事件類型（<code>keydown</code> 、 <code>keypress</code> 和 <code>keyup</code>）用來表示鍵盤執行哪種動作。</p> + +<div class="note"><strong>注意：</strong> <code>KeyboardEvent</code> 僅顯示在鍵盤上發生的事。當你需要進行文字輸入的操作，請使用 HTML5 <code><a href="/en-US/docs/DOM/DOM_event_reference/input" rel="custom">input</a></code> event 代替 <code>KeyboardEvent</code> 。舉例來說，當使用者在手寫系統，例如平板電腦，輸入文字時，並不會啟動 key events 。</div> + +<h2 id="Constructor">Constructor</h2> + +<dl> + <dt>{{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}}</dt> + <dd>建立一 <code>KeyboardEvent</code> object。</dd> +</dl> + +<h2 id="Methods">Methods</h2> + +<p><em>本介面（ interface）亦繼承其父， {{domxref("UIEvent")}} 和 {{domxref("Event")}} ，的 methods</em></p> + +<dl> + <dt>{{domxref("KeyboardEvent.getModifierState()")}}</dt> + <dd>回傳一 {{jsxref("Boolean")}}。用來表示當事件建立時，修飾鍵（例如 <kbd>Alt</kbd>、 <kbd>Shift</kbd>、 <kbd>Ctrl</kbd>、或是 <kbd>Meta</kbd>） 是否是按下的。</dd> + <dt>{{domxref("KeyboardEvent.initKeyEvent()")}}{{deprecated_inline}}</dt> + <dd>初始化一個 <code>KeyboardEvent</code> object。這個 method 只有 Gecko 有在使用（其他瀏覽器是使用 {{domxref("KeyboardEvent.initKeyboardEvent()")}}），並且不應該再繼續使用。現代的標準規範是使用 {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}} constructor。</dd> + <dt>{{domxref("KeyboardEvent.initKeyboardEvent()")}}{{deprecated_inline}}</dt> + <dd>初始化一個 <code>KeyboardEvent</code> object。 Gecko 從未實作過該 method （Gecko 是使用 {{domxref("KeyboardEvent.initKeyEvent()")}}) ，並且不應該再繼續使用。現代的標準規範是使用 {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}} constructor。</dd> +</dl> + +<h2 id="Properties">Properties</h2> + +<p><em>本介面（ interface）亦繼承其父，{{domxref("UIEvent")}} 和 {{domxref("Event")}} ，的 properties 。</em></p> + +<dl> + <dt>{{domxref("KeyboardEvent.altKey")}} {{Readonlyinline}}</dt> + <dd>一個 {{jsxref("Boolean")}} 。用來表示在事件建立時， <kbd>Alt</kbd> （OS X 中是 <kbd>Option</kbd> 或 <kbd>⌥</kbd> ） 鍵是否執行中。</dd> + <dt>{{domxref("KeyboardEvent.char")}} {{Non-standard_inline}}{{Deprecated_inline}}{{Readonlyinline}}</dt> + <dd>一個 {{domxref("DOMString")}} ，返回鍵盤對應的字符。若是該鍵對應一個實際的字符，則其值為對應該字符的一個非空的 Unicode 字串；若沒對應的話，則返回一個空字串。 + <div class="note"><strong>Note:</strong> If the key is used as a macro that inserts multiple characters, this attribute's value is the entire string, not just the first character.</div> + + <div class="warning"><strong>警告:</strong> 在 DOM Level 3 Events ，該 propertie 已被移除。現在只有 IE9+ 支持它。</div> + </dd> + <dt>{{domxref("KeyboardEvent.charCode")}} {{Deprecated_inline}}{{Readonlyinline}}</dt> + <dd>Returns a {{jsxref("Number")}} representing the Unicode reference number of the key; this attribute is used only by the <code>keypress</code> event. For keys whose <code>char</code> attribute contains multiple characters, this is the Unicode value of the first character in that attribute. In Firefox 26 this returns codes for printable characters. + <div class="warning"><strong>警告:</strong> 此 attribute 已被淘汰。如果可以，建議使用 {{domxref("KeyboardEvent.key")}} 。</div> + </dd> + <dt>{{domxref("KeyboardEvent.code")}} {{Readonlyinline}}</dt> + <dd>一個 {{domxref("DOMString")}} 。返回事件對應的按鍵的代碼。</dd> + <dt>{{domxref("KeyboardEvent.ctrlKey")}} {{Readonlyinline}}</dt> + <dd>一個 {{jsxref("Boolean")}} 。用來表示在事件建立時， <kbd>Ctrl</kbd> 鍵是否執行中。</dd> + <dt>{{domxref("KeyboardEvent.isComposing")}} {{Readonlyinline}}</dt> + <dd>一個 {{jsxref("Boolean")}} 。用來表示其觸發時間是否在 <code>compositionstart</code> 和 <code>compositionend</code> 之間。</dd> + <dt>{{domxref("KeyboardEvent.key")}} {{Readonlyinline}}</dt> + <dd>一個 {{domxref("DOMString")}} ，用來事件對應的按鍵的值（key value）。</dd> + <dt>{{domxref("KeyboardEvent.keyCode")}} {{deprecated_inline}}{{Readonlyinline}}</dt> + <dd>Returns a {{jsxref("Number")}} representing a system and implementation dependent numerical code identifying the unmodified value of the pressed key. + <div class="warning"><strong>警告:</strong> 此 attribute 已被淘汰。如果可以，建議使用{{domxref("KeyboardEvent.key")}} 。</div> + </dd> + <dt>{{domxref("KeyboardEvent.locale")}} {{Readonlyinline}}</dt> + <dd>Returns a {{domxref("DOMString")}} representing a locale string indicating the locale the keyboard is configured for. This may be the empty string if the browser or device doesn't know the keyboard's locale. + <div class="note"><strong>Note:</strong> This does not describe the locale of the data being entered. A user may be using one keyboard layout while typing text in a different language.</div> + </dd> + <dt>{{domxref("KeyboardEvent.location")}}<a> {{Readonlyinline}}</a></dt> + <dd>Returns a {{jsxref("Number")}} representing the location of the key on the keyboard or other input device.</dd> + <dt>{{domxref("KeyboardEvent.metaKey")}} {{Readonlyinline}}</dt> + <dd>Returns a {{jsxref("Boolean")}} that is <code>true</code> if the <kbd>Meta</kbd> (on Mac keyboards, the <kbd>⌘ Command</kbd> key; on Windows keyboards, the Windows key (<kbd>⊞</kbd>)) key was active when the key event was generated.</dd> + <dt>{{domxref("KeyboardEvent.repeat")}} {{Readonlyinline}}</dt> + <dd>Returns a {{jsxref("Boolean")}} that is <code>true</code> if the key is being held down such that it is automatically repeating.</dd> + <dt>{{domxref("KeyboardEvent.shiftKey")}} {{Readonlyinline}}</dt> + <dd>Returns a {{jsxref("Boolean")}} that is <code>true</code> if the <kbd>Shift</kbd> key was active when the key event was generated.</dd> + <dt>{{domxref("KeyboardEvent.which")}} {{deprecated_inline}}{{Readonlyinline}}</dt> + <dd>Returns a {{jsxref("Number")}} representing a system and implementation dependent numeric code identifying the unmodified value of the pressed key; this is usually the same as <code>keyCode</code>. + <div class="warning"><strong>警告:</strong> 此 attribute 已被淘汰。如果可以，建議使用 {{domxref("KeyboardEvent.key")}} 。</div> + </dd> +</dl> + +<h2 id="注意">注意</h2> + +<p>KeyboardEvent 有 <code>keydown</code> 、 <code>keypress</code> 、 <code>keyup</code> 三種事件。對大多數的按鍵而言， Gecko 觸發事件的順序如下：</p> + +<ol> + <li>當按鍵按下時，會送出 <code>keydown</code> event 。</li> + <li>當按鍵不是特殊鍵（ modifier key），例如<kbd>Ctrl</kbd> 、<kbd>Alt</kbd>……等等，會送出 <code>keypress</code> event 。</li> + <li>當按鍵放開時，會送出 <code>keyup</code> event 。</li> +</ol> + +<h3 id="特殊狀況">特殊狀況</h3> + +<p>某些按鍵，例如 <kbd>Caps Lock</kbd> 、 <kbd>Num Lock</kbd> 和 <kbd>Scroll Lock</kbd> 能切換鍵盤上的 LED 燈。在 Windows 和 Linux 系統上，這些按鍵只會觸發 <code>keydown</code> 和 <code>keyup</code> 事件。但是 Linux 上的 Firefox 12 或更早的版本亦會觸發 <code>keypress</code> 事件。</p> + +<p>而在 Mac 電腦則不同， <kbd>Caps Lock</kbd> 只會觸發 <code>keydown</code> 事件；而 <kbd>Num Lock</kbd> 則是只有舊版的 Mac 電腦（2007 或之前的版本）才有，現在的 Mac 即便使用外部鍵盤也不支援 <kbd>Num Lock</kbd> 。雖說舊版的 Mac 電腦支援 <kbd>Num Lock</kbd> 鍵，但 <kbd>Num Lock</kbd> 並不會執行任何 KeyboardEvent；而 Gecko 瀏覽器在特殊情況（外接一個有 <kbd>F14</kbd> 的鍵盤）下能支援 <kbd>Scroll Lock</kbd> ，但是它會產生 <code>keypress</code> 事件。這個異常狀態是個 bug ，詳情可參考 {{bug(602812)}}。</p> + +<h3 id="自動迴圈（Auto-Repeat_）的執行">自動迴圈（Auto-Repeat ）的執行</h3> + +<p>當按鍵按下去不放時，它會開始一個自動迴圈。並導致觸發一系列的相似事件，如下所示：</p> + +<ol> + <li><code>keydown</code></li> + <li><code>keypress</code></li> + <li><code>keydown</code></li> + <li><code>keypress</code></li> + <li>（不斷重複，直到使用者放開按鍵）</li> + <li><code>keyup</code></li> +</ol> + +<p>在 DOM Level 3 說明書有提及這問題是會發生的。其中所存在的問題如下說明：</p> + +<h4 id="部分_GTK_環境，例如_Ubuntu_9.4_，的自動迴圈">部分 GTK 環境，例如 Ubuntu 9.4 ，的自動迴圈</h4> + +<p>部分的 GTK-based 環境之中，自動迴圈在發生的過程中會自動觸發電腦本機的 key-up 事件。然而，對 Gecko 而言，並沒有方法可以分辨使用者重複點擊按鍵與自動迴圈（按鍵按住不放）的差異。在這類的環境下，按鍵按住不放會重複執行下列事件：</p> + +<ol> + <li><code>keydown</code></li> + <li><code>keypress</code></li> + <li><code>keyup</code></li> + <li><code>keydown</code></li> + <li><code>keypress</code></li> + <li><code>keyup</code></li> + <li>（不斷重複，直到使用者放開按鍵）</li> + <li><code>keyup</code></li> +</ol> + +<p>不幸地，在這些環境之下，web content 亦沒有方法告訴使用者重複點擊按鍵與自動迴圈的差異。</p> + +<h4 id="Gecko_5.0_以前的自動迴圈">Gecko 5.0 以前的自動迴圈</h4> + +<p>Gecko 5.0 {{geckoRelease('5.0')}} 以前，在不同平台上，鍵盤的處理與現在相比較不統一。</p> + +<dl> + <dt>Windows</dt> + <dd>自動迴圈的結果與 Gecko 4.0 或更新的版本類似</dd> + <dt>Mac</dt> + <dd>在第一個 keydown 執行後，僅執行 keypress 事件，一直到案件放開（即送出 keyup 事件指令），過程中不會送出任何 keydown 事件。</dd> + <dt>Linux</dt> + <dd>鍵盤事件的執行根據平台不同而有所不同。它有可能表現得像是 Windows 也有可能像 Mac ，這取決於本地的事件模型（native event model）是如何執行的。</dd> +</dl> + +<h2 id="範例">範例</h2> + +<pre class="brush: js"><!DOCTYPE html> +<html> +<head> +<script> +var metaChar = false; +var exampleKey = 16; + +function keyEvent(event) { + var key = event.keyCode || event.which; + var keychar = String.fromCharCode(key); + if (key == exampleKey) { + metaChar = true; + } + if (key != exampleKey) { + if (metaChar) { + alert("Combination of metaKey + " + keychar); + metaChar = false; + } else { + alert("Key pressed " + key); + } + } +} + +function metaKeyUp (event) { + var key = event.keyCode || event.which; + + if (key == exampleKey) { + metaChar = false; + } +} +</script> +</head> + +<body onkeydown="keyEvent(event)" onkeyup="metaKeyUp(event)"> +</body> +</html> +</pre> + +<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('DOM3 Events', '#interface-KeyboardEvent', 'KeyboardEvent')}}</td> + <td>{{Spec2('DOM3 Events')}}</td> + <td>原始定義</td> + </tr> + </tbody> +</table> + +<p>The <code>KeyboardEvent</code> interface specification went through numerous draft versions, first under DOM Events Level 2 where it was dropped as no consensus arose, then under DOM Events Level 3. This led to the implementation of non-standard initialization methods, the early DOM Events Level 2 version, {{domxref("KeyboardEvent.initKeyEvent()")}} by Gecko browsers and the early DOM Events Level 3 version, {{domxref("KeyboardEvent.initKeyboardEvent()")}} by others. Both have been superseded by the modern usage of a constructor: {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}}.</p> + +<h2 id="瀏覽器支援度">瀏覽器支援度</h2> + +<p>More compatibility data is available on other pages:</p> + +<ul> + <li><code>.code</code> ：請參考《瀏覽器支援度》的 {{domxref("KeyboardEvent.code")}} 部分。</li> + <li><code>.key</code>：請參考《瀏覽器支援度》的 {{domxref("KeyboardEvent.key")}} 部分。</li> + <li><code>.getModifierState()</code> ：請參考《瀏覽器支援度》的 {{domxref("KeyboardEvent.getModifierState")}} 部分。</li> +</ul> + +<p>{{CompatibilityTable}}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>constructor</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("31.0")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>.char</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>.charCode</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>.code</code></td> + <td colspan="5" rowspan="1">See Browser compatibility of {{domxref("KeyboardEvent.code")}}.</td> + </tr> + <tr> + <td><code>.isComposing</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop("31.0")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>.key</code></td> + <td colspan="5" rowspan="1">See Browser compatibility of {{domxref("KeyboardEvent.key")}}.</td> + </tr> + <tr> + <td><code>.keyCode</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>.locale</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>.location</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("15.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>.repeat</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("28.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>.which</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>.getModifierState()</code></td> + <td colspan="5" rowspan="1">See Browser compatibility of {{domxref("KeyboardEvent.getModifierState")}}</td> + </tr> + <tr> + <td><code>.initKeyboardEvent()</code></td> + <td>{{CompatVersionUnknown}}<sup>[1]</sup></td> + <td>{{CompatNo}}<sup>[2]</sup></td> + <td>{{CompatIE("9.0")}}<sup>[3]</sup></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}<sup>[1]</sup></td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>constructor</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("31.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>.char</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>.charCode</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>.code</code></td> + <td colspan="5" rowspan="1">See Browser compatibility of {{domxref("KeyboardEvent.code")}}.</td> + </tr> + <tr> + <td><code>.isComposing</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile("31.0")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>.key</code></td> + <td colspan="6">See Browser compatibility table of {{domxref("KeyboardEvent.key")}}.</td> + </tr> + <tr> + <td><code>.keyCode</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>.locale</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>.location</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("15.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>.repeat</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("28.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>.which</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>.getModifierState()</code></td> + <td colspan="5" rowspan="1">See Browser compatibility of {{domxref("KeyboardEvent.getModifierState")}}</td> + </tr> + <tr> + <td><code>.initKeyboardEvent()</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] The arguments of <code>initKeyboardEvent()</code> of WebKit and Blink's are different from the definition in DOM Level 3 Events. The method is: <code>initKeyboardEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in views::AbstractView viewArg, in DOMString keyIndentifierArg, in number locationArg, in boolean ctrlKeyArg, in boolean altKeyArg, in boolean shiftKeyArg, in boolean metaKeyArg, in boolean altGraphKeyArg)</code></p> + +<p>[2] Gecko won't support <code>initKeyboardEvent()</code> because supporting it completely breaks feature detection of web applications. See {{Bug(999645)}}.</p> + +<p>[3] The argument of <code>initKeyboardEvent()</code> of IE is different from the definition in DOM Level 3 Events. The method is: <code>initKeyboardEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in views::AbstractView viewArg, in DOMString keyArg, in number locationArg, in DOMString modifierListArg, in boolean repeatArt, in DOMString locationArg)</code>. See <a href="http://msdn.microsoft.com/en-us/library/ie/ff975297%28v=vs.85%29.aspx">document of <code>initKeyboardEvent()</code> in MSDN</a>.</p> + +<p><a href="http://www.howtocreate.co.uk/tutorials/javascript/domevents#domevld1">[4]</a> Note that manually firing an event does <em>not</em> generate the default action associated with that event. For example, manually firing a key event does not cause that letter to appear in a focused text input. In the case of UI events, this is important for security reasons, as it prevents scripts from simulating user actions that interact with the browser itself.</p> diff --git a/files/zh-tw/web/api/keyboardevent/keyboardevent/index.html b/files/zh-tw/web/api/keyboardevent/keyboardevent/index.html new file mode 100644 index 0000000000..3af92514bb --- /dev/null +++ b/files/zh-tw/web/api/keyboardevent/keyboardevent/index.html @@ -0,0 +1,202 @@ +--- +title: KeyboardEvent() +slug: Web/API/KeyboardEvent/KeyboardEvent +translation_of: Web/API/KeyboardEvent/KeyboardEvent +--- +<p>{{APIRef("DOM Events")}}</p> + +<p><strong><code>KeyboardEvent()</code></strong> constructor 能用來建立一個新的 {{domxref("KeyboardEvent")}}。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"> <em>event</em> = new KeyboardEvent(<em>typeArg</em>, <em>KeyboardEventInit</em>);</pre> + +<h3 id="參數">參數</h3> + +<dl> + <dt><em>typeArg</em></dt> + <dd>一 {{domxref("DOMString")}} 用來表示事件名稱。</dd> + <dt><em>KeyboardEventInit</em>{{optional_inline}}</dt> + <dd>一個 <code>KeyboardEventInit</code> dictionary，能接受以下參數： + <table class="standard-table"> + <thead> + <tr> + <th>參數</th> + <th>可選</th> + <th>默認值</th> + <th>類型</th> + <th>說明</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>"key"</code></td> + <td>●</td> + <td><code>""</code></td> + <td>{{domxref("DOMString")}}</td> + <td>用來設定 {{domxref("KeyboardEvent.key")}} 的值</td> + </tr> + <tr> + <td><code>"code"</code></td> + <td>●</td> + <td><code>""</code></td> + <td>{{domxref("DOMString")}}</td> + <td>用來設定 {{domxref("KeyboardEvent.code")}} 的值</td> + </tr> + <tr> + <td><code>"location"</code></td> + <td>●</td> + <td>0</td> + <td><code>unsigned long</code></td> + <td>用來設定 {{domxref("KeyboardEvent.location")}} 的值</td> + </tr> + <tr> + <td><code>"ctrlKey"</code></td> + <td>●</td> + <td><code>false</code></td> + <td>{{jsxref("Boolean")}}</td> + <td>用來設定 {{domxref("KeyboardEvent.ctrlKey")}} 的值</td> + </tr> + <tr> + <td><code>"shiftKey"</code></td> + <td>●</td> + <td><code>false</code></td> + <td>{{jsxref("Boolean")}}</td> + <td>用來設定 {{domxref("KeyboardEvent.shiftKey")}} 的值</td> + </tr> + <tr> + <td>"altKey"</td> + <td>●</td> + <td><code>false</code></td> + <td>{{jsxref("Boolean")}}</td> + <td>用來設定 {{domxref("KeyboardEvent.altKey")}} 的值</td> + </tr> + <tr> + <td>"metaKey"</td> + <td>●</td> + <td><code>false</code></td> + <td>{{jsxref("Boolean")}}</td> + <td>用來設定 {{domxref("KeyboardEvent.metaKey")}} 的值</td> + </tr> + <tr> + <td>"repeat"</td> + <td>●</td> + <td><code>false</code></td> + <td>{{jsxref("Boolean")}}</td> + <td>用來設定 {{domxref("KeyboardEvent.repeat")}} 的值</td> + </tr> + <tr> + <td>"isComposing"</td> + <td>●</td> + <td><code>false</code></td> + <td>{{jsxref("Boolean")}}</td> + <td>用來設定 {{domxref("KeyboardEvent.isComposing")}} 的值</td> + </tr> + <tr> + <td>"charCode"</td> + <td>●</td> + <td>0</td> + <td><code>unsigned long</code></td> + <td>用來設定 {{domxref("KeyboardEvent.charCode")}} 的值</td> + </tr> + <tr> + <td>"keyCode"</td> + <td>●</td> + <td>0</td> + <td><code>unsigned long</code></td> + <td>用來設定 {{domxref("KeyboardEvent.keyCode")}} 的值</td> + </tr> + <tr> + <td>"which"</td> + <td>●</td> + <td>0</td> + <td><code>unsigned long</code></td> + <td>用來設定 {{domxref("KeyboardEvent.which")}} 的值</td> + </tr> + </tbody> + </table> + + <div class="note"> + <p><em> <code>KeyboardEventInit</code> dictionary 亦接受 {{domxref("UIEvent.UIEvent", "UIEventInit")}} 和{{domxref("Event.Event", "EventInit")}} 所接受的參數。</em></p> + </div> + </dd> +</dl> + +<h2 id="Specifications" name="Specifications">規格</h2> + +<table class="standard-table" style="height: 49px; width: 1000px;"> + <thead> + <tr> + <th scope="col">Specification</th> + <th scope="col">Status</th> + <th scope="col">Comment</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{SpecName('DOM3 Events','#interface-KeyboardEvent','KeyboardEvent()')}}</td> + <td>{{Spec2('DOM3 Events')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器支援度">瀏覽器支援度</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatGeckoDesktop(13) }}</td> + <td>{{ CompatNo() }}</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatUnknown() }}</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>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + <th>Chrome for Android</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{ CompatUnknown }}</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatGeckoMobile(31) }}</td> + <td>{{ CompatNo() }}</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="延伸閱讀">延伸閱讀</h2> + +<ul> + <li>{{domxref("KeyboardEvent")}} ，此 constructer 所建立的 object 的 interface</li> +</ul> diff --git a/files/zh-tw/web/api/media_streams_api/index.html b/files/zh-tw/web/api/media_streams_api/index.html new file mode 100644 index 0000000000..6813a5d1d6 --- /dev/null +++ b/files/zh-tw/web/api/media_streams_api/index.html @@ -0,0 +1,87 @@ +--- +title: Media Capture and Streams API (Media Stream) +slug: Web/API/Media_Streams_API +tags: + - API + - Audio + - Media + - Video +translation_of: Web/API/Media_Streams_API +--- +<div>{{DefaultAPISidebar("Media Capture and Streams")}}</div> + +<p><span class="seoSummary">該<strong>媒體捕獲和流</strong>API，通常被稱為<strong>媒體流API</strong>或者乾脆<strong>MediaStream API</strong>，是關係到一個API<a href="/en-US/docs/Web/API/WebRTC_API">的WebRTC</a>提供流式音頻和視頻數據的支持。</span>它提供了用於處理流及其組成軌道的接口和方法，與數據格式關聯的約束，異步使用數據時的成功和錯誤回調以及在此過程中觸發的事件。</p> + +<h2 id="概念和用法">概念和用法</h2> + +<p>該API基於{{domxref("MediaStream")}}對象的操作，該對象代表與音頻或視頻相關的數據流。請參閱“<a href="/en-US/docs/WebRTC/taking_webcam_photos#Get_the_video">獲取視頻”中</a>的示例。</p> + +<p>A <code>MediaStream</code> consists of zero or more {{domxref("MediaStreamTrack")}} objects, representing various audio or video <strong>tracks</strong>. Each <code>MediaStreamTrack</code> may have one or more <strong>channels</strong>. The channel represents the smallest unit of a media stream, such as an audio signal associated with a given speaker, like <em>left</em> or <em>right</em> in a stereo audio track.</p> + +<p><code>MediaStream</code> objects have a single <strong>input</strong> and a single <strong>output</strong>. A <code>MediaStream</code> object generated by {{domxref("MediaDevices.getUserMedia", "getUserMedia()")}} is called <em>local</em>, and has as its source input one of the user's cameras or microphones. A non-local <code>MediaStream</code> may be representing to a media element, like {{HTMLElement("video")}} or {{HTMLElement("audio")}}, a stream originating over the network, and obtained via the WebRTC {{domxref("RTCPeerConnection")}} API, or a stream created using the <a href="/en-US/docs/Web/API/Web_Audio_API">Web Audio API</a> {{domxref("MediaStreamAudioSourceNode")}}.</p> + +<p>The output of the <code>MediaStream</code> object is linked to a <strong>consumer</strong>. It can be a media elements, like {{HTMLElement("audio")}} or {{HTMLElement("video")}}, the WebRTC {{domxref("RTCPeerConnection")}} API or a <a href="/en-US/docs/Web/API/Web_Audio_API">Web Audio API</a> {{domxref("MediaStreamAudioSourceNode")}}.</p> + +<h2 id="Interfaces">Interfaces</h2> + +<p>In these reference articles, you'll find the fundamental information you'll need to know about each of the interfaces that make up the Media Capture and Streams API.</p> + +<div class="index"> +<ul> + <li>{{domxref("BlobEvent")}}</li> + <li>{{domxref("CanvasCaptureMediaStreamTrack")}}</li> + <li>{{domxref("InputDeviceInfo")}}</li> + <li>{{domxref("MediaDeviceKind")}}</li> + <li>{{domxref("MediaDeviceInfo")}}</li> + <li>{{domxref("MediaDevices")}}</li> + <li>{{domxref("MediaStream")}}</li> + <li>{{domxref("MediaStreamConstraints")}}</li> + <li>{{domxref("MediaStreamEvent")}}</li> + <li>{{domxref("MediaStreamTrack")}}</li> + <li>{{domxref("MediaStreamTrackEvent")}}</li> + <li>{{domxref("MediaTrackCapabilities")}}</li> + <li>{{domxref("MediaTrackConstraints")}}</li> + <li>{{domxref("MediaTrackSettings")}}</li> + <li>{{domxref("MediaTrackSupportedConstraints")}}</li> + <li>{{domxref("NavigatorUserMedia")}}</li> + <li>{{domxref("NavigatorUserMediaError")}}</li> + <li>{{domxref("OverconstrainedError")}}</li> + <li>{{domxref("URL")}}</li> +</ul> +</div> + +<p>Early versions of the Media Capture and Streams API specification included separate <code>AudioStreamTrack</code> and <code>VideoStreamTrack</code> interfaces—each based upon {{domxref("MediaStreamTrack")}}—which represented streams of those types. These no longer exist, and you should update any existing code to instead use <code>MediaStreamTrack</code> directly.</p> + +<h2 id="Events">Events</h2> + +<div class="index"> +<ul> + <li>{{event("addtrack")}}</li> + <li>{{event("ended")}}</li> + <li>{{event("muted")}}</li> + <li>{{event("overconstrained")}}</li> + <li>{{event("removetrack")}}</li> + <li>{{event("started")}}</li> + <li>{{event("unmuted")}}</li> +</ul> +</div> + +<h2 id="Guides_and_tutorials">Guides and tutorials</h2> + +<p>The articles below provide additional guidance and how-to information that will help you learn to use the API, and how to perform specific tasks that you may wish to handle.</p> + +<p>{{LandingPageListSubpages}}</p> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<div class="hidden">此頁面上的兼容性表是根據結構化數據生成的。如果您想提供數據，請查看<a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>並向我們發送請求請求。</div> + +<p>{{Compat("api.MediaStream")}}</p> + +<h2 id="也可以看看">也可以看看</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/WebRTC_API">WebRTC</a> -API簡介頁</li> + <li>{{domxref("mediaDevices.getUserMedia()")}}</li> + <li><a href="/en-US/docs/Web/API/WebRTC_API/Taking_still_photos">使用WebRTC拍攝靜態照片</a>：有關使用<code>getUserMedia()</code>。</li> +</ul> diff --git a/files/zh-tw/web/api/mediaquerylist/index.html b/files/zh-tw/web/api/mediaquerylist/index.html new file mode 100644 index 0000000000..ef3128a4b8 --- /dev/null +++ b/files/zh-tw/web/api/mediaquerylist/index.html @@ -0,0 +1,144 @@ +--- +title: MediaQueryList +slug: Web/API/MediaQueryList +translation_of: Web/API/MediaQueryList +--- +<div>{{APIRef("CSSOM View")}}{{SeeCompatTable}}</div> + +<p><code>MediaQueryList</code> 物件維護一組針對 {{ domxref("document") }} 的 <a href="/en-US/docs/CSS/Media_queries" style="line-height: 19.0909080505371px;" title="CSS/Media queries">media querie</a> , 並且當 media querie 相對應的文件狀態改變時，觸發註冊的事件處理器通知之。</p> + +<p><span style="font-family: consolas,monaco,andale mono,monospace; line-height: 19.0909080505371px;">MediaQueryList</span><span style="line-height: 19.0909080505371px;"> 物件讓我們不用一直定期去偵測，而是直接去觀察文件的狀態變化。</span></p> + +<h2 id="Method_overview" name="Method_overview">Method overview</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td><code>void <a href="/en-US/docs/DOM/MediaQueryList#addListener()" title="DOM/MediaQueryList#addListener()">addListener</a>(MediaQueryListListener listener);</code></td> + </tr> + <tr> + <td><code>void <a href="/en-US/docs/DOM/MediaQueryList#removeListener()" title="DOM/MediaQueryList#removeListener()">removeListener</a>(MediaQueryListListener listener);</code></td> + </tr> + </tbody> +</table> + +<h2 id="Properties" name="Properties">Properties</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td class="header">Property</td> + <td class="header">Type</td> + <td class="header">Description</td> + </tr> + <tr> + <td><code>matches</code></td> + <td><code>boolean</code></td> + <td><code>true</code> 當 {{ domxref("document") }} 目前狀態符合 media query list 所維護的條件; 否則 false。 唯獨<strong>。</strong></td> + </tr> + <tr> + <td><code>media</code></td> + <td><code>DOMString</code></td> + <td>序列化 (serialized) 的 media query list.</td> + </tr> + </tbody> +</table> + +<h2 id="Methods" name="Methods">Methods</h2> + +<h3 id="addListener()" name="addListener()">addListener()</h3> + +<p>添加一個新的事件處理器 (listener)，若 <span style="line-height: 19.0909080505371px;">listener </span>已存在則無作用。</p> + +<pre>void addListener( + MediaQueryListListener listener +);</pre> + +<h4 id="Parameter_(for_addListener_method)" name="Parameter_(for_addListener_method)">Parameter (for addListener method)</h4> + +<dl> + <dt><code>listener</code></dt> + <dd>當 media query 對應的狀態改變時所觸發的事件處理函數 ({{ domxref("MediaQueryListListener") }})。</dd> +</dl> + +<h3 id="removeListener()" name="removeListener()">removeListener()</h3> + +<p><span style="line-height: 19.0909080505371px;">移除一個事件處理器 (</span><span style="line-height: 19.0909080505371px;">listener)，若 </span><span style="line-height: 19.0909080505371px;">listener 不</span><span style="line-height: 19.0909080505371px;">存在則無作用。</span></p> + +<pre>void removeListener( + MediaQueryListListener listener +);</pre> + +<h4 id="Parameter_(for_removeListener_method)" name="Parameter_(for_removeListener_method)">Parameter (for removeListener method)</h4> + +<dl> + <dt><code>listener</code></dt> + <dd>欲移除的<span style="line-height: 19.0909080505371px;">事件處理函數</span><span style="line-height: 19.0909080505371px;"> ({{ domxref("MediaQueryListListener") }})。</span></dd> +</dl> + +<h2 id="Browser_compatibility" name="Browser_compatibility">瀏覽器相容性</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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>9</td> + <td>{{ CompatGeckoDesktop("6.0") }}</td> + <td>10</td> + <td>12.1</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="Specification" name="Specification"> </h2> + +<h2 id="Specification" name="Specification">規範標準</h2> + +<ul> + <li><a class="external" href="http://dev.w3.org/csswg/cssom-view/#the-mediaquerylist-interface" title="http://dev.w3.org/csswg/cssom-view/#the-mediaquerylist-interface">The CSSOM View Module: The MediaQueryList Interface</a></li> +</ul> + +<h2 id="See_also" name="See_also">延伸閱讀</h2> + +<ul> + <li><a href="/en-US/docs/CSS/Media_queries" title="CSS/Media queries">Media queries</a></li> + <li><a href="/en-US/docs/CSS/Using_media_queries_from_code" title="CSS/Using media queries from code">Using media queries from code</a></li> + <li>{{ domxref("window.matchMedia()") }}</li> + <li>{{ domxref("MediaQueryListListener") }}</li> +</ul> diff --git a/files/zh-tw/web/api/mediasource/activesourcebuffers/index.html b/files/zh-tw/web/api/mediasource/activesourcebuffers/index.html new file mode 100644 index 0000000000..90777f675c --- /dev/null +++ b/files/zh-tw/web/api/mediasource/activesourcebuffers/index.html @@ -0,0 +1,126 @@ +--- +title: MediaSource.activeSourceBuffers +slug: Web/API/MediaSource/activeSourceBuffers +translation_of: Web/API/MediaSource/activeSourceBuffers +--- +<div>{{APIRef("Media Source Extensions")}}{{SeeCompatTable}}</div> + +<p><code><strong>activeSourceBuffers</strong></code> 是 {{domxref("MediaSource")}} 介面的唯讀屬性，回傳一個 {{domxref("SourceBufferList")}} 物件，含有在 {{domxref("SourceBuffers")}} 之中的 {{domxref("SourceBuffer")}} 物件子集合—物件的串列提供被選擇的影片軌 (video track), 啟用的音軌 (audio tracks), 以及顯示或隱藏的字軌。</p> + +<h2 id="語法">語法</h2> + +<pre class="brush: js">var myActiveSourceBuffers = mediaSource.activeSourceBuffers;</pre> + +<h3 id="回傳值">回傳值</h3> + +<p>一個 {{domxref("SourceBufferList")}} 。</p> + +<h2 id="範例">範例</h2> + +<p>以下的片段基於 Nick Desaulniers 所編纂的簡單範例（<a href="http://nickdesaulniers.github.io/netfix/demo/bufferAll.html">觀看實際演示</a>，或者<a href="https://github.com/nickdesaulniers/netfix/blob/gh-pages/demo/bufferAll.html">下載原始碼</a> 以利更進一步研究。）</p> + +<pre class="brush: js language-js"><code class="language-js"><span class="keyword token">function</span> sourceOpen <span class="punctuation token">(</span>_<span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="comment token"> //console.log(this.readyState); // open +</span> <span class="keyword token">var</span> mediaSource <span class="operator token">=</span> <span class="keyword token">this</span><span class="punctuation token">;</span> + <span class="keyword token">var</span> sourceBuffer <span class="operator token">=</span> mediaSource<span class="punctuation token">.</span><span class="function token">addSourceBuffer<span class="punctuation token">(</span></span>mimeCodec<span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="function token">fetchAB<span class="punctuation token">(</span></span>assetURL<span class="punctuation token">,</span> <span class="keyword token">function</span> <span class="punctuation token">(</span>buf<span class="punctuation token">)</span> <span class="punctuation token">{</span> + sourceBuffer<span class="punctuation token">.</span><span class="function token">addEventListener<span class="punctuation token">(</span></span><span class="string token">'updateend'</span><span class="punctuation token">,</span> <span class="keyword token">function</span> <span class="punctuation token">(</span>_<span class="punctuation token">)</span> <span class="punctuation token">{</span> + mediaSource<span class="punctuation token">.</span><span class="function token">endOfStream<span class="punctuation token">(</span></span><span class="punctuation token">)</span><span class="punctuation token">; + console.log(mediaSource.activeSourceBuffers); + // will contain the source buffer that was added above, + // as it is selected for playing in the video player</span> + video<span class="punctuation token">.</span><span class="function token">play<span class="punctuation token">(</span></span><span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="comment token"> //console.log(mediaSource.readyState); // ended +</span> <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + sourceBuffer<span class="punctuation token">.</span><span class="function token">appendBuffer<span class="punctuation token">(</span></span>buf<span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span><span class="punctuation token">; + +...</span></code></pre> + +<h2 id="規格">規格</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規格</th> + <th scope="col">狀態</th> + <th scope="col">注釋</th> + </tr> + <tr> + <td>{{SpecName('Media Source Extensions', '#widl-MediaSource-activeSourceBuffers', 'activeSourceBuffers')}}</td> + <td>{{Spec2('Media Source Extensions')}}</td> + <td>Initial definition.</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>23</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("25.0")}}<sup>[1]</sup><br> + {{CompatGeckoDesktop("42.0")}}</td> + <td>11<sup>[2]</sup></td> + <td>15</td> + <td>8</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>4.4.4</td> + <td>{{CompatVersionUnknown}}</td> + <td> + <p>{{CompatNo}}</p> + </td> + <td>{{CompatNo}}</td> + <td>11</td> + <td>30</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] 在切換 about:config 偏好設定 media.mediasource.enabled 為 true 時可以使用。此外，支援只限於白名單內的網站，如：YouTube, Netflix, 以及其他熱門的串流網站。白名單已經被移除且 Media Source Extensions 在 42+ 對所有網站已預設為啟用。</p> + +<p>[2] 只在 Windows 8+ 上有效。</p> + +<h2 id="相關資料">相關資料</h2> + +<ul> + <li>{{domxref("SourceBuffer")}}</li> + <li>{{domxref("SourceBufferList")}}</li> +</ul> diff --git a/files/zh-tw/web/api/mediasource/duration/index.html b/files/zh-tw/web/api/mediasource/duration/index.html new file mode 100644 index 0000000000..b9fab966e4 --- /dev/null +++ b/files/zh-tw/web/api/mediasource/duration/index.html @@ -0,0 +1,149 @@ +--- +title: MediaSource.duration +slug: Web/API/MediaSource/duration +translation_of: Web/API/MediaSource/duration +--- +<div>{{APIRef("Media Source Extensions")}}{{SeeCompatTable}}</div> + +<p>{{domxref("MediaSource")}} 介面的 <code><strong>duration</strong></code> 屬性用來取得以及設置正被表示的媒體時間長度。</p> + +<h2 id="語法">語法</h2> + +<pre class="brush: js">mediaSource.duration = 5.5; // 5.5 seconds + +var myDuration = mediaSource.duration;</pre> + +<h3 id="回傳值">回傳值</h3> + +<p>單位為秒的 double 型別。</p> + +<h3 id="錯誤">錯誤</h3> + +<p>當設置此屬性一個新的值時以下錯誤可能發生。</p> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">錯誤</th> + <th scope="col">解釋</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>InvalidAccessError</code></td> + <td>嘗試設置的時間長度是負值，或者 <code>NaN</code>。</td> + </tr> + <tr> + <td><code>InvalidStateError</code></td> + <td>{{domxref("MediaSource.readyState")}} 不是 <code>open</code>，或者 {{domxref("MediaSource.sourceBuffers")}} 中一個或多個以上的 {{domxref("SourceBuffer")}} 物件正在被更新（例如：他們的 {{domxref("SourceBuffer.updating")}} 屬性為 <code>true</code>。）</td> + </tr> + </tbody> +</table> + +<h2 id="範例">範例</h2> + +<p>以下的片段基於 Nick Desaulniers 所編纂的簡單範例（<a href="http://nickdesaulniers.github.io/netfix/demo/bufferAll.html">觀看實際演示</a>，或者<a href="https://github.com/nickdesaulniers/netfix/blob/gh-pages/demo/bufferAll.html">下載原始碼</a>以利更進一步研究。）</p> + +<pre class="brush: js language-js"><code class="language-js"><span class="keyword token">function</span> sourceOpen <span class="punctuation token">(</span>_<span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="comment token"> //console.log(this.readyState); // open +</span> <span class="keyword token">var</span> mediaSource <span class="operator token">=</span> <span class="keyword token">this</span><span class="punctuation token">;</span> + <span class="keyword token">var</span> sourceBuffer <span class="operator token">=</span> mediaSource<span class="punctuation token">.</span><span class="function token">addSourceBuffer<span class="punctuation token">(</span></span>mimeCodec<span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="function token">fetchAB<span class="punctuation token">(</span></span>assetURL<span class="punctuation token">,</span> <span class="keyword token">function</span> <span class="punctuation token">(</span>buf<span class="punctuation token">)</span> <span class="punctuation token">{</span> + sourceBuffer<span class="punctuation token">.</span><span class="function token">addEventListener<span class="punctuation token">(</span></span><span class="string token">'updateend'</span><span class="punctuation token">,</span> <span class="keyword token">function</span> <span class="punctuation token">(</span>_<span class="punctuation token">)</span> <span class="punctuation token">{</span> + mediaSource<span class="punctuation token">.</span><span class="function token">endOfStream<span class="punctuation token">(</span></span><span class="punctuation token">)</span><span class="punctuation token">; + mediaSource.duration = 120;</span> + video<span class="punctuation token">.</span><span class="function token">play<span class="punctuation token">(</span></span><span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="comment token"> //console.log(mediaSource.readyState); // ended +</span> <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + sourceBuffer<span class="punctuation token">.</span><span class="function token">appendBuffer<span class="punctuation token">(</span></span>buf<span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span><span class="punctuation token">; + +...</span></code></pre> + +<h2 id="規格">規格</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規格</th> + <th scope="col">狀態</th> + <th scope="col">注釋</th> + </tr> + <tr> + <td>{{SpecName('Media Source Extensions', '#widl-MediaSource-duration', 'duration')}}</td> + <td>{{Spec2('Media Source Extensions')}}</td> + <td>Initial definition.</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>23</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("25.0")}}<sup>[1]</sup><br> + {{CompatGeckoDesktop("42.0")}}</td> + <td>11<sup>[2]</sup></td> + <td>15</td> + <td>8</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>4.4.4</td> + <td>{{CompatVersionUnknown}}</td> + <td> + <p>{{CompatNo}}</p> + </td> + <td>{{CompatNo}}</td> + <td>11</td> + <td>30</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] 在切換 <code>about:config</code> 偏好設定 <code>media.mediasource.enabled</code> 為 <code>true</code>時可以使用。此外，支援只限於白名單內的網站，如：YouTube, Netflix, 以及其他熱門的串流網站。白名單已經被移除且 Media Source Extensions 在 42+ 對所有網站已預設為啟用。</p> + +<p>[2] 只在 Windows 8+ 上有效。</p> + +<h2 id="相關資料">相關資料</h2> + +<ul> + <li>{{domxref("SourceBuffer")}}</li> + <li>{{domxref("SourceBufferList")}}</li> +</ul> diff --git a/files/zh-tw/web/api/mediasource/index.html b/files/zh-tw/web/api/mediasource/index.html new file mode 100644 index 0000000000..0006121f46 --- /dev/null +++ b/files/zh-tw/web/api/mediasource/index.html @@ -0,0 +1,144 @@ +--- +title: MediaSource +slug: Web/API/MediaSource +translation_of: Web/API/MediaSource +--- +<p>{{APIRef("Media Source Extensions")}}{{SeeCompatTable}}</p> + +<p><a href="/en-US/docs/Web/API/Media_Source_Extensions_API">Media Source Extensions API</a> 的 <strong><code>MediaSource</code></strong> 介面代表 {{domxref("HTMLMediaElement")}} 物件的媒體資料來源。一個 <code>MediaSource</code> 物件可以被附加到一個 {{domxref("HTMLMediaElement")}} 以被用戶代理 (user agent) 播放。</p> + +<p>{{InheritanceDiagram}}</p> + +<h2 id="建構子_Constructor">建構子 (Constructor)</h2> + +<dl> + <dt>{{domxref("MediaSource.MediaSource", "MediaSource()")}}</dt> + <dd>建構且回傳一個新的 <code>MediaSource</code> 物件但不與任何來源緩衝 (source buffers) 關聯 (associate)。</dd> +</dl> + +<h2 id="屬性_Properties">屬性 (Properties)</h2> + +<dl> + <dt>{{domxref("MediaSource.sourceBuffers")}} {{readonlyInline}}</dt> + <dd>回傳一個含有與此 <code>MediaSource</code> 關聯的 {{domxref("SourceBuffer")}} 物件串列的 {{domxref("SourceBufferList")}} 物件。</dd> + <dt>{{domxref("MediaSource.activeSourceBuffers")}} {{readonlyInline}}</dt> + <dd>回傳一個 {{domxref("SourceBufferList")}} 物件，含有 {{domxref("SourceBuffers")}} 的子集合 {{domxref("SourceBuffer")}} 物件 — 物件的串列提供被選擇的影片軌 (video track), 啟用的音軌 (audio tracks), 以及顯示或隱藏的字軌。</dd> + <dt>{{domxref("MediaSource.readyState")}} {{readonlyInline}}</dt> + <dd>回傳一個列舉類型表示目前 <code>MediaSource</code> 的狀態：沒有附加到媒體元件 (<code>closed</code>)，已經附加且可以接收 {{domxref("SourceBuffer")}} 物件 (<code>open</code>)，已經附加但是串流已經經由 {{domxref("MediaSource.endOfStream()")}} 結束 (<code>ended</code>)。</dd> + <dt>{{domxref("MediaSource.duration")}}</dt> + <dd>取得或設置現在正被表示的媒體的時間長度。</dd> + <dt> + <h3 id="事件處理函數_Event_handlers">事件處理函數 (Event handlers)</h3> + + + </dt> + <dt>{{domxref("MediaSource.onsourceclose")}}</dt> + <dd><code>sourceclose</code> 事件的事件處理函數。</dd> + <dt>{{domxref("MediaSource.onsourceended")}}</dt> + <dd><code>sourceended</code> 事件的事件處理函數。</dd> + <dt>{{domxref("MediaSource.onsourceopen")}}</dt> + <dd><code>sourceopen</code> 事件的事件處理函數。</dd> +</dl> + +<dl> +</dl> + +<dl> +</dl> + +<h2 id="方法_Methods">方法 (Methods)</h2> + +<p><em>從親介面 (parent interface) {{domxref("EventTarget")}} 繼承屬性。</em></p> + +<dl> + <dt>{{domxref("MediaSource.addSourceBuffer()")}}</dt> + <dd>依據指定的 MIME 類型建立一個新的 {{domxref("SourceBuffer")}} 且將其加入 <code>MediaSource</code> 的 {{domxref("SourceBuffers")}} 串列。</dd> + <dt>{{domxref("MediaSource.clearLiveSeekableRange()")}}</dt> + <dd>清除先前藉由呼叫 <code>setLiveSeekableRange()</code> 所設定的可尋找範圍。</dd> + <dt>{{domxref("MediaSource.endOfStream()")}}</dt> + <dd>示意串流的結束。</dd> + <dt>{{domxref("MediaSource.removeSourceBuffer()")}}</dt> + <dd>從與此 <code>MediaSource</code> 物件關聯的 {{domxref("SourceBuffers")}} 串列移除指定的 {{domxref("SourceBuffer")}}。</dd> + <dt>{{domxref("MediaSource.setLiveSeekableRange()")}}</dt> + <dd>設定使用者可以在媒體元素中的可尋找範圍。</dd> +</dl> + +<h2 id="靜態方法_Static_methods">靜態方法 (Static methods)</h2> + +<dl> + <dt>{{domxref("MediaSource.isTypeSupported()")}}</dt> + <dd>回傳一個 {{domxref("Boolean")}} 值表示指定的 MIME 類型是否被現在的用戶代理支援 — 意即可否成功的為該 MIME 類型建立 {{domxref("SourceBuffer")}} 物件。</dd> +</dl> + +<h2 id="範例">範例</h2> + +<p>以下簡單的範例儘快的載入一個個影片塊 (chunk) 且儘快的播放。這個範例是由 Nick Desaulniers 所撰寫且可以<a href="http://nickdesaulniers.github.io/netfix/demo/bufferAll.html">在此實際觀看</a>（您也可以<a href="https://github.com/nickdesaulniers/netfix/blob/gh-pages/demo/bufferAll.html">下載原始碼</a>以更進一步研究）</p> + +<pre class="brush: js notranslate">var video = document.querySelector('video'); + +var assetURL = 'frag_bunny.mp4'; +// Need to be specific for Blink regarding codecs +// ./mp4info frag_bunny.mp4 | grep Codec +var mimeCodec = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"'; + +if ('MediaSource' in window && MediaSource.isTypeSupported(mimeCodec)) { + var mediaSource = new MediaSource(); + //console.log(mediaSource.readyState); // closed + video.src = URL.createObjectURL(mediaSource); + mediaSource.addEventListener('sourceopen', sourceOpen); +} else { + console.error('Unsupported MIME type or codec: ', mimeCodec); +} + +function sourceOpen (_) { + //console.log(this.readyState); // open + var mediaSource = this; + var sourceBuffer = mediaSource.addSourceBuffer(mimeCodec); + fetchAB(assetURL, function (buf) { + sourceBuffer.addEventListener('updateend', function (_) { + mediaSource.endOfStream(); + video.play(); + //console.log(mediaSource.readyState); // ended + }); + sourceBuffer.appendBuffer(buf); + }); +}; + +function fetchAB (url, cb) { + console.log(url); + var xhr = new XMLHttpRequest; + xhr.open('get', url); + xhr.responseType = 'arraybuffer'; + xhr.onload = function () { + cb(xhr.response); + }; + xhr.send(); +};</pre> + +<h2 id="規格">規格</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規格</th> + <th scope="col">狀態</th> + <th scope="col">註釋</th> + </tr> + <tr> + <td>{{SpecName('Media Source Extensions', '#mediasource', 'MediaSource')}}</td> + <td>{{Spec2('Media Source Extensions')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="相容性表格">相容性表格</h2> + +<div>{{Compat("api.MediaSource")}}</div> + +<h2 id="相關資料">相關資料</h2> + +<ul> + <li>{{domxref("SourceBuffer")}}</li> + <li>{{domxref("SourceBufferList")}}</li> +</ul> diff --git a/files/zh-tw/web/api/mediasource/mediasource/index.html b/files/zh-tw/web/api/mediasource/mediasource/index.html new file mode 100644 index 0000000000..54e9e6dfef --- /dev/null +++ b/files/zh-tw/web/api/mediasource/mediasource/index.html @@ -0,0 +1,122 @@ +--- +title: MediaSource.MediaSource() +slug: Web/API/MediaSource/MediaSource +translation_of: Web/API/MediaSource/MediaSource +--- +<div>{{APIRef("Media Source Extensions")}}{{SeeCompatTable}}</div> + +<p>{{domxref("MediaSource")}} 介面的 <code><strong>MediaSource()</strong></code> 建構子建構且回傳一個沒有與任何來源緩衝 (source buffer) 關聯的新 <code>MediaSource</code> 物件。</p> + +<h2 id="語法">語法</h2> + +<pre class="brush: js">var mediaSource = new MediaSource();</pre> + +<h3 id="參數">參數</h3> + +<p>無。</p> + +<h2 id="範例">範例</h2> + +<p>以下的片段擷取自 Nick Desaulniers 所編纂的簡單範例（<a href="http://nickdesaulniers.github.io/netfix/demo/bufferAll.html">觀看實際演示</a>，或者<a href="https://github.com/nickdesaulniers/netfix/blob/gh-pages/demo/bufferAll.html">下載原始碼</a> 以利更進一步研究。）</p> + +<pre class="brush: js">var video = document.querySelector('video'); + +var assetURL = 'frag_bunny.mp4'; +// Need to be specific for Blink regarding codecs +// ./mp4info frag_bunny.mp4 | grep Codec +var mimeCodec = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"'; + +if ('MediaSource' in window && MediaSource.isTypeSupported(mimeCodec)) { + var mediaSource = new MediaSource; + //console.log(mediaSource.readyState); // closed + video.src = URL.createObjectURL(mediaSource); + mediaSource.addEventListener('sourceopen', sourceOpen); +} else { + console.error('Unsupported MIME type or codec: ', mimeCodec); +} + +... +</pre> + +<h2 id="規格">規格</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規格</th> + <th scope="col">狀態</th> + <th scope="col">註釋</th> + </tr> + <tr> + <td>{{SpecName('Media Source Extensions', '#mediasource', 'MediaSource')}}</td> + <td>{{Spec2('Media Source Extensions')}}</td> + <td>Initial definition.</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>23</td> + <td>{{CompatGeckoDesktop("25.0")}}<sup>[1]</sup><br> + {{CompatGeckoDesktop("42.0")}}</td> + <td>11<sup>[2]</sup></td> + <td>15</td> + <td>8</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>4.4.4</td> + <td> + <p>{{CompatNo}}</p> + </td> + <td>{{CompatNo}}</td> + <td>11</td> + <td>30</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] 在切換 <code>about:config</code> 偏好設定 <code>media.mediasource.enabled</code> 為 <code>true</code> 時可以使用。此外，支援只限於白名單內的網站，如：YouTube, Netflix, 以及其他熱門的串流網站。白名單已經被移除且 Media Source Extensions 在 42+ 對所有網站已預設為啟用。</p> + +<p>[2] 只在 Windows 8+ 上有效。</p> + +<h2 id="相關資料">相關資料</h2> + +<ul> + <li>{{domxref("SourceBuffer")}}</li> + <li>{{domxref("SourceBufferList")}}</li> +</ul> diff --git a/files/zh-tw/web/api/mediasource/readystate/index.html b/files/zh-tw/web/api/mediasource/readystate/index.html new file mode 100644 index 0000000000..b7e5f1835b --- /dev/null +++ b/files/zh-tw/web/api/mediasource/readystate/index.html @@ -0,0 +1,136 @@ +--- +title: MediaSource.readyState +slug: Web/API/MediaSource/readyState +translation_of: Web/API/MediaSource/readyState +--- +<div>{{APIRef("Media Source Extensions")}}{{SeeCompatTable}}</div> + +<p>{{domxref("MediaSource")}} 介面的唯讀屬性 <code><strong>readyState</strong></code> 回傳表示當前 <code>MediaSource</code> 狀態的列舉值。三種可能的值為：</p> + +<ul> + <li><code>closed</code>: 來源 (source) 目前沒有附加到媒體元件 (media element) 。</li> + <li><code>open</code>: 來源已經附加且可以接收 {{domxref("SourceBuffer")}} 物件。</li> + <li><code>ended</code>: 來源已經附加但是串流已經經由 {{domxref("MediaSource.endOfStream()")}} 結束。</li> +</ul> + +<h2 id="語法">語法</h2> + +<pre class="brush: js">var myReadyState = mediaSource.readyState;</pre> + +<h3 id="回傳值">回傳值</h3> + +<p>一個 {{domxref("DOMString")}}。</p> + +<h2 id="範例">範例</h2> + +<p>以下片段是由 Nick Desaulniers 所撰寫的簡單範例（<a href="http://nickdesaulniers.github.io/netfix/demo/bufferAll.html">在此實際觀看</a>，或者<a href="https://github.com/nickdesaulniers/netfix/blob/gh-pages/demo/bufferAll.html">下載原始碼</a>以更進一步研究）</p> + +<pre class="brush: js language-js"><code class="language-js"><span class="keyword token">if</span> <span class="punctuation token">(</span><span class="string token">'MediaSource'</span> <span class="keyword token">in</span> window <span class="operator token">&&</span> MediaSource<span class="punctuation token">.</span><span class="function token">isTypeSupported<span class="punctuation token">(</span></span>mimeCodec<span class="punctuation token">)</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="keyword token">var</span> mediaSource <span class="operator token">=</span> <span class="keyword token">new</span> <span class="class-name token">MediaSource</span><span class="punctuation token">;</span> + <span class="comment token"> //console.log(mediaSource.readyState); // closed +</span> video<span class="punctuation token">.</span>src <span class="operator token">=</span> URL<span class="punctuation token">.</span><span class="function token">createObjectURL<span class="punctuation token">(</span></span>mediaSource<span class="punctuation token">)</span><span class="punctuation token">;</span> + mediaSource<span class="punctuation token">.</span><span class="function token">addEventListener<span class="punctuation token">(</span></span><span class="string token">'sourceopen'</span><span class="punctuation token">,</span> sourceOpen<span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> <span class="keyword token">else</span> <span class="punctuation token">{</span> + console<span class="punctuation token">.</span><span class="function token">error<span class="punctuation token">(</span></span><span class="string token">'Unsupported MIME type or codec: '</span><span class="punctuation token">,</span> mimeCodec<span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +<span class="keyword token">function</span> sourceOpen <span class="punctuation token">(</span>_<span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="comment token"> //console.log(this.readyState); // open +</span> <span class="keyword token">var</span> mediaSource <span class="operator token">=</span> <span class="keyword token">this</span><span class="punctuation token">;</span> + <span class="keyword token">var</span> sourceBuffer <span class="operator token">=</span> mediaSource<span class="punctuation token">.</span><span class="function token">addSourceBuffer<span class="punctuation token">(</span></span>mimeCodec<span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="function token">fetchAB<span class="punctuation token">(</span></span>assetURL<span class="punctuation token">,</span> <span class="keyword token">function</span> <span class="punctuation token">(</span>buf<span class="punctuation token">)</span> <span class="punctuation token">{</span> + sourceBuffer<span class="punctuation token">.</span><span class="function token">addEventListener<span class="punctuation token">(</span></span><span class="string token">'updateend'</span><span class="punctuation token">,</span> <span class="keyword token">function</span> <span class="punctuation token">(</span>_<span class="punctuation token">)</span> <span class="punctuation token">{</span> + mediaSource<span class="punctuation token">.</span><span class="function token">endOfStream<span class="punctuation token">(</span></span><span class="punctuation token">)</span><span class="punctuation token">;</span> + video<span class="punctuation token">.</span><span class="function token">play<span class="punctuation token">(</span></span><span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="comment token"> //console.log(mediaSource.readyState); // ended +</span> <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + sourceBuffer<span class="punctuation token">.</span><span class="function token">appendBuffer<span class="punctuation token">(</span></span>buf<span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span><span class="punctuation token">;</span></code></pre> + +<h2 id="規格">規格</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規格</th> + <th scope="col">狀態</th> + <th scope="col">註釋</th> + </tr> + <tr> + <td>{{SpecName('Media Source Extensions', '#widl-MediaSource-readyState', 'readyState')}}</td> + <td>{{Spec2('Media Source Extensions')}}</td> + <td>Initial definition.</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>23</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("25.0")}}<sup>[1]</sup><br> + {{CompatGeckoDesktop("42.0")}}</td> + <td>11<sup>[2]</sup></td> + <td>15</td> + <td>8</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>4.4.4</td> + <td>{{CompatVersionUnknown}}</td> + <td> + <p>{{CompatNo}}</p> + </td> + <td>{{CompatNo}}</td> + <td>11</td> + <td>30</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] 在切換 <code>about:config</code> preference <code>media.mediasource.enabled</code> 為 <code>true</code> 時可以使用。此外，支援只限於白名單內的網站，如：YouTube, Netflix, 以及其他熱門的串流網站。白名單已經被移除且 Media Source Extensions 在 42+ 對所有網站已預設為啟用。</p> + +<p>[2] 只在 Windows 8+ 上有效。</p> + +<h2 id="相關資料">相關資料</h2> + +<ul> + <li>{{domxref("SourceBuffer")}}</li> + <li>{{domxref("SourceBufferList")}}</li> +</ul> diff --git a/files/zh-tw/web/api/mouseevent/index.html b/files/zh-tw/web/api/mouseevent/index.html new file mode 100644 index 0000000000..43f2a3a26d --- /dev/null +++ b/files/zh-tw/web/api/mouseevent/index.html @@ -0,0 +1,317 @@ +--- +title: MouseEvent +slug: Web/API/MouseEvent +translation_of: Web/API/MouseEvent +--- +<p id="Summary">{{APIRef("DOM Events")}}</p> + +<p><code><strong>MouseEvent</strong></code> 介面表示了由使用者經指標裝置（如滑鼠）進行互動所發生的事件。常見的 <code>MouseEvent</code> 實作事件包括了 {{event("click")}}、{{event("dblclick")}}、{{event("mouseup")}} 與 {{event("mousedown")}}。</p> + +<p><code>MouseEvent</code> 繼承自 {{domxref("UIEvent")}}，而 <code>UIEvent</code> 則繼承自 {{domxref("Event")}}。雖然 {{domxref("MouseEvent.initMouseEvent()")}} 方法仍然向下相容新的瀏覽器，但現今應該使用 {{domxref("MouseEvent.MouseEvent", "MouseEvent()")}} 建構式來建立 <code>MouseEvent</code> 物件。</p> + +<p>另外還有一些特定的事件繼承自 <code>MouseEvent</code>：{{domxref("WheelEvent")}} 及 {{domxref("DragEvent")}}。</p> + +<h2 id="建構式">建構式</h2> + +<dl> + <dt>{{domxref("MouseEvent.MouseEvent", "MouseEvent()")}}</dt> + <dd>建立一個 <code>MouseEvent</code> 物件。</dd> +</dl> + +<h2 id="屬性">屬性</h2> + +<p><em>此介面也繼承了其父介面 {{domxref("UIEvent")}} 與 {{domxref("Event")}} 的屬性</em></p> + +<dl> + <dt>{{domxref("MouseEvent.altKey")}} {{readonlyinline}}</dt> + <dd>Returns <code>true</code> if the <kbd>alt</kbd> key was down when the mouse event was fired.</dd> + <dt>{{domxref("MouseEvent.button")}} {{readonlyinline}}</dt> + <dd>The button number that was pressed when the mouse event was fired. </dd> + <dt>{{domxref("MouseEvent.buttons")}} {{readonlyinline}} {{gecko_minversion_inline("15.0")}}</dt> + <dd> + <p>The buttons being pressed when the mouse event was fired</p> + </dd> + <dt>{{domxref("MouseEvent.clientX")}} {{readonlyinline}}</dt> + <dd>The X coordinate of the mouse pointer in local (DOM content) coordinates.</dd> + <dt>{{domxref("MouseEvent.clientY")}} {{readonlyinline}}</dt> + <dd>The Y coordinate of the mouse pointer in local (DOM content) coordinates.</dd> + <dt>{{domxref("MouseEvent.ctrlKey")}} {{readonlyinline}}</dt> + <dd>Returns <code>true</code> if the <kbd>control</kbd> key was down when the mouse event was fired.</dd> + <dt>{{domxref("MouseEvent.metaKey")}} {{readonlyinline}}</dt> + <dd>Returns <code>true</code> if the <kbd>meta</kbd> key was down when the mouse event was fired.</dd> + <dt>{{domxref("MouseEvent.movementX")}} {{readonlyinline}}</dt> + <dd>The X coordinate of the mouse pointer relative to the position of the last {{event("mousemove")}} event.</dd> + <dt>{{domxref("MouseEvent.movementY")}} {{readonlyinline}}</dt> + <dd>The Y coordinate of the mouse pointer relative to the position of the last {{event("mousemove")}} event.</dd> + <dt>{{domxref("MouseEvent.offsetX")}} {{readonlyinline}}{{experimental_inline}}</dt> + <dd>The X coordinate of the mouse pointer relative to the position of the padding edge of the target node.</dd> + <dt>{{domxref("MouseEvent.offsetY")}} {{readonlyinline}}{{experimental_inline}}</dt> + <dd>The Y coordinate of the mouse pointer relative to the position of the padding edge of the target node.</dd> + <dt>{{domxref("MouseEvent.pageX")}} {{readonlyinline}}{{experimental_inline}}</dt> + <dd>The X coordinate of the mouse pointer relative to the whole document.</dd> + <dt>{{domxref("MouseEvent.pageY")}} {{readonlyinline}}{{experimental_inline}}</dt> + <dd>The Y coordinate of the mouse pointer relative to the whole document.</dd> + <dt>{{domxref("MouseEvent.region")}} {{readonlyinline}}</dt> + <dd>Returns the id of the hit region affected by the event. If no hit region is affected, <code>null</code> is returned.</dd> + <dt>{{domxref("MouseEvent.relatedTarget")}} {{readonlyinline}}</dt> + <dd> + <p>The secondary target for the event, if there is one.</p> + </dd> + <dt>{{domxref("MouseEvent.screenX")}} {{readonlyinline}}</dt> + <dd>The X coordinate of the mouse pointer in global (screen) coordinates.</dd> + <dt>{{domxref("MouseEvent.screenY")}} {{readonlyinline}}</dt> + <dd>The Y coordinate of the mouse pointer in global (screen) coordinates.</dd> + <dt>{{domxref("MouseEvent.shiftKey")}} {{readonlyinline}}</dt> + <dd>Returns <code>true</code> if the <kbd>shift</kbd> key was down when the mouse event was fired.</dd> + <dt>{{domxref("MouseEvent.which")}} {{non-standard_inline}} {{readonlyinline}}</dt> + <dd>The button being pressed when the mouse event was fired.</dd> + <dt>{{domxref("MouseEvent.mozPressure")}} {{non-standard_inline()}} {{readonlyinline}}</dt> + <dd>The amount of pressure applied to a touch or tablet device when generating the event; this value ranges between <code>0.0</code> (minimum pressure) and <code>1.0</code> (maximum pressure).</dd> + <dt>{{domxref("MouseEvent.mozInputSource")}} {{non-standard_inline()}} {{readonlyinline}}</dt> + <dd> + <p>The type of device that generated the event (one of the <code>MOZ_SOURCE_*</code> constants listed below). This lets you, for example, determine whether a mouse event was generated by an actual mouse or by a touch event (which might affect the degree of accuracy with which you interpret the coordinates associated with the event).</p> + </dd> + <dt>{{domxref("MouseEvent.webkitForce")}} {{non-standard_inline()}} {{readonlyinline}}</dt> + <dd>The amount of pressure applied when clicking</dd> + <dt>{{domxref("MouseEvent.x")}} {{experimental_inline}}{{readonlyinline}}</dt> + <dd>Alias for {{domxref("MouseEvent.clientX")}}.</dd> + <dt>{{domxref("MouseEvent.y")}} {{experimental_inline}}{{readonlyinline}}</dt> + <dd>Alias for {{domxref("MouseEvent.clientY")}}</dd> +</dl> + +<h2 id="Constants">Constants</h2> + +<dl> + <dt>{{domxref("MouseEvent.WEBKIT_FORCE_AT_MOUSE_DOWN")}} {{non-standard_inline}}{{readonlyinline}}</dt> + <dd>Minimum force necessary for a normal click</dd> + <dt>{{domxref("MouseEvent.WEBKIT_FORCE_AT_FORCE_MOUSE_DOWN")}} {{non-standard_inline}}{{readonlyinline}}</dt> + <dd>Minimum force necessary for a force click</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>此介面也繼承了其父介面 {{domxref("UIEvent")}} 與 {{domxref("Event")}} 的方法</em></p> + +<dl> + <dt>{{domxref("MouseEvent.getModifierState()")}}</dt> + <dd>Returns the current state of the specified modifier key. See the {{domxref("KeyboardEvent.getModifierState")}}() for details.</dd> + <dt>{{domxref("MouseEvent.initMouseEvent()")}} {{deprecated_inline}}</dt> + <dd>Initializes the value of a <code>MouseEvent</code> created. If the event has already being dispatched, this method does nothing.</dd> +</dl> + +<h2 id="範例">範例</h2> + +<p>This example demonstrates simulating a click (that is programmatically generating a click event) on a checkbox using DOM methods. </p> + +<pre class="brush: js">function simulateClick() { + var evt = new <a href="/en-US/docs/Web/API/MouseEvent">MouseEvent</a>("click", { + bubbles: true, + cancelable: true, + view: window + }); + var cb = document.getElementById("checkbox"); //element to click on + var canceled = !cb.<a href="/en-US/docs/Web/API/EventTarget.dispatchEvent" rel="internal" title="en/DOM/element.dispatchEvent">dispatchEvent</a>(evt); + if(canceled) { + // A handler called preventDefault + alert("canceled"); + } else { + // None of the handlers called preventDefault + alert("not canceled"); + } +} +document.getElementById("button").addEventListener('click', simulateClick);</pre> + +<pre class="brush: html"><p><label><input type="checkbox" id="checkbox"> Checked</label> +<p><button id="button">Click me</button></pre> + +<p>Click on the button to see how the sample works:</p> + +<p>{{ EmbedLiveSample('Example', '', '', '') }}</p> + +<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('CSSOM View','#extensions-to-the-mouseevent-interface', 'MouseEvent')}}</td> + <td>{{Spec2('CSSOM View')}}</td> + <td>Redefines <code>MouseEvent</code> from long to double. This means that a <code>PointerEvent</code> whose <code>pointerType</code> is mouse will be a double.</td> + </tr> + <tr> + <td>{{SpecName("HTML WHATWG", "#dom-mouseevent-region", "MouseEvent.region")}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>From {{SpecName('DOM3 Events')}}, added the <code>region</code> property.</td> + </tr> + <tr> + <td>{{SpecName('Pointer Lock','#extensions-to-the-mouseevent-interface','MouseEvent')}}</td> + <td>{{Spec2('Pointer Lock')}}</td> + <td>From {{SpecName('DOM3 Events')}}, added <code>movementX</code> and <code>movementY</code> properties.</td> + </tr> + <tr> + <td>{{SpecName('CSSOM View', '#extensions-to-the-mouseevent-interface', 'MouseEvent')}}</td> + <td>{{Spec2('CSSOM View')}}</td> + <td>From {{SpecName('DOM3 Events')}}, added <code>offsetX</code> and <code>offsetY</code>, <code>pageX</code> and <code>pageY</code>, <code>x,</code> and <code>y</code> properties. Redefined screen, page, client and coordinate (x and y) properties as <code>double</code> from <code>long</code>.</td> + </tr> + <tr> + <td>{{SpecName('DOM3 Events','#events-mouseevents','MouseEvent')}}</td> + <td>{{Spec2('DOM3 Events')}}</td> + <td>From {{SpecName('DOM2 Events')}}, added the <code>MouseEvent()</code> constructor, the <code>getModifierState()</code> method and the <code>buttons</code> property.</td> + </tr> + <tr> + <td>{{SpecName('DOM2 Events','#Events-MouseEvent','MouseEvent')}}</td> + <td>{{Spec2('DOM2 Events')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility" name="Browser_compatibility">瀏覽器相容性</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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>{{CompatVersionUnknown()}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{CompatVersionUnknown()}}</td> + </tr> + <tr> + <td>{{domxref("MouseEvent.movementX","movementX")}}<br> + {{domxref("MouseEvent.movementY","movementY")}}</td> + <td>{{CompatChrome(37)}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{CompatVersionUnknown()}} {{property_prefix("moz")}}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + <tr> + <td>{{ domxref("MouseEvent.buttons", "buttons") }}</td> + <td>{{CompatChrome(43)}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>{{ domxref("MouseEvent.which", "which") }}</td> + <td>{{CompatChrome(1)}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>1.0</td> + <td>9.0</td> + <td>5.0</td> + <td>1.0</td> + </tr> + <tr> + <td>{{domxref("MouseEvent.getModifierState()", "getModifierState()")}}</td> + <td>{{CompatChrome(47)}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{CompatGeckoDesktop(15)}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{CompatVersionUnknown()}}</td> + </tr> + <tr> + <td>{{domxref("MouseEvent.mozPressure", "mozPressure")}} and {{domxref("MouseEvent.mozInputSource", "mozInputSource")}} {{non-standard_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{CompatGeckoDesktop(2)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>{{domxref("MouseEvent.MouseEvent", "MouseEvent()")}}</td> + <td>{{CompatChrome(45)}}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{CompatGeckoDesktop(11)}}</td> + <td>9.0</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + <tr> + <td>{{domxref("MouseEvent.region")}}</td> + <td>{{CompatChrome(51)}}<sup>[1]</sup></td> + <td>{{ CompatUnknown() }}</td> + <td>{{CompatGeckoDesktop(32)}}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + <tr> + <td>{{domxref("MouseEvent.offsetX")}}, and {{domxref("MouseEvent.offsetY")}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>9</td> + <td>{{CompatGeckoDesktop(40)}}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + <tr> + <td>{{domxref("MouseEvent.screenX")}}, {{domxref("MouseEvent.screenY")}}, {{domxref("MouseEvent.clientX")}}, and {{domxref("MouseEvent.Y")}} are double instead of long.</td> + <td>{{CompatChrome(56)}}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Requires enabling the <code>ExperimentalCanvasFeatures</code> flag.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>Its direct parent, {{domxref("UIEvent")}}.</li> +</ul> diff --git a/files/zh-tw/web/api/mutationobserver/index.html b/files/zh-tw/web/api/mutationobserver/index.html new file mode 100644 index 0000000000..e2e1e50bfd --- /dev/null +++ b/files/zh-tw/web/api/mutationobserver/index.html @@ -0,0 +1,276 @@ +--- +title: MutationObserver +slug: Web/API/MutationObserver +translation_of: Web/API/MutationObserver +--- +<p>{{APIRef("DOM")}}</p> + +<p><code>MutationObserver</code> 提供開發人員一個方法，來對 <a href="/en-US/docs/DOM">DOM</a> tree 的變動來作反應，這被設計用來替換在 DOM3 事件規範中的 <a href="/en-US/docs/DOM/Mutation_events">Mutation Events</a>。</p> + +<h2 id="建構式">建構式</h2> + +<h3 id="MutationObserver()"><code>MutationObserver()</code></h3> + +<p>以下舉例為一個新的 DOM mutation observers 建構式。</p> + +<pre class="syntaxbox">new MutationObserver( + function callback +); +</pre> + +<h6 id="參數">參數</h6> + +<dl> + <dt><code>callback</code></dt> + <dd>這個函式會在 DOM 有變化時被呼叫，observer 會用兩個參數來呼叫它，第一個是 <code><a href="#MutationRecord">MutationRecord</a> </code>物件陣列，而第二個參數則是觀察者目標本身。</dd> +</dl> + +<h2 id="Instance_methods">Instance methods</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td><code>void <a href="#observe()">observe</a>( {{domxref("Node")}} target, <a href="#MutationObserverInit">MutationObserverInit</a> options );</code></td> + </tr> + <tr> + <td><code>void <a href="#disconnect()">disconnect</a>();</code></td> + </tr> + <tr> + <td><code>Array <a href="#takeRecords()">takeRecords</a>();</code></td> + </tr> + </tbody> +</table> + +<div class="note"> +<p><strong>筆記</strong>: {{domxref("Node")}} target should not be confused with <a href="https://nodejs.org/en/">NodeJS</a>.</p> +</div> + +<h3 id="observe()"><code>observe()</code></h3> + +<p>Registers the <code>MutationObserver</code> instance to receive notifications of DOM mutations on the specified node.</p> + +<pre class="syntaxbox">void observe( + {{domxref("Node")}} target, + <a href="#MutationObserverInit"><code>MutationObserverInit</code></a> options +); +</pre> + +<h6 id="Parameters">Parameters</h6> + +<dl> + <dt><code>target</code></dt> + <dd>The {{domxref("Node")}} on which to observe DOM mutations.</dd> + <dt><code>options</code></dt> + <dd>A <a href="#MutationObserverInit"><code>MutationObserverInit</code></a> object, specifies which DOM mutations should be reported.</dd> +</dl> + +<div class="note">NOTE: Adding an observer to an element is just like addEventListener, if you observe the element multiple times it does not make a difference. Meaning if you observe element twice, the observe callback does not fire twice, nor will you have to run disconnect() twice. In other words, once an element is observed, observing it again with the same observer instance will do nothing. However if the callback object is different it will of course add another observer to it.</div> + +<h3 id="disconnect()"><code>disconnect()</code></h3> + +<p>Stops the <code>MutationObserver</code> instance from receiving notifications of DOM mutations. Until the <a href="#observe()"><code>observe()</code></a> method is used again, observer's callback will not be invoked.</p> + +<pre class="syntaxbox">void disconnect(); +</pre> + +<h3 id="takeRecords()"><code>takeRecords()</code></h3> + +<p>Empties the <code>MutationObserver</code> instance's record queue and returns what was in there.</p> + +<pre class="syntaxbox">Array takeRecords(); +</pre> + +<h6 id="Return_value">Return value</h6> + +<p>Returns an Array of <a href="#MutationRecord"><code>MutationRecord</code>s</a>.</p> + +<h2 id="MutationObserverInit"><code>MutationObserverInit</code></h2> + +<p><code>MutationObserverInit</code> is an object which can specify the following properties:</p> + +<div class="note">NOTE: At the very least, <code>childList</code>, <code>attributes</code>, or <code>characterData</code> must be set to <code>true</code>. Otherwise, "An invalid or illegal string was specified" error is thrown.</div> + +<table class="standard-table"> + <tbody> + <tr> + <td class="header">Property</td> + <td class="header">Description</td> + </tr> + <tr> + <td><code>childList</code></td> + <td>Set to <code>true</code> if additions and removals of the target node's child elements (including text nodes) are to be observed.</td> + </tr> + <tr> + <td><code>attributes</code></td> + <td>Set to <code>true</code> if mutations to target's attributes are to be observed.</td> + </tr> + <tr> + <td><code>characterData</code></td> + <td>Set to <code>true</code> if mutations to target's data are to be observed.</td> + </tr> + <tr> + <td><code>subtree</code></td> + <td>Set to <code>true</code> if mutations to not just target, but also target's descendants are to be observed.</td> + </tr> + <tr> + <td><code>attributeOldValue</code></td> + <td>Set to <code>true</code> if <code>attributes</code> is set to <code>true</code> and target's attribute value before the mutation needs to be recorded.</td> + </tr> + <tr> + <td><code>characterDataOldValue</code></td> + <td>Set to <code>true</code> if <code>characterData</code> is set to <code>true</code> and target's data before the mutation needs to be recorded.</td> + </tr> + <tr> + <td><code>attributeFilter</code></td> + <td>Set to an array of attribute local names (without namespace) if not all attribute mutations need to be observed.</td> + </tr> + </tbody> +</table> + +<h2 id="MutationRecord"><code>MutationRecord</code></h2> + +<p><code>MutationRecord</code> is the object that will be passed to the observer's callback. It has the following properties:</p> + +<table class="standard-table"> + <tbody> + <tr> + <td class="header">Property</td> + <td class="header">Type</td> + <td class="header">Description</td> + </tr> + <tr> + <td><code>type</code></td> + <td><code>String</code></td> + <td>Returns <code>attributes</code> if the mutation was an attribute mutation, <code>characterData</code> if it was a mutation to a <code>CharacterData</code> node, and <code>childList</code> if it was a mutation to the tree of nodes.</td> + </tr> + <tr> + <td><code>target</code></td> + <td><code>{{domxref("Node")}}</code></td> + <td>Returns the node the mutation affected, depending on the <code>type</code>. For <code>attributes</code>, it is the element whose attribute changed. For <code>characterData</code>, it is the <code>CharacterData</code> node. For <code>childList</code>, it is the node whose children changed.</td> + </tr> + <tr> + <td><code>addedNodes</code></td> + <td><code>{{domxref("NodeList")}}</code></td> + <td>Return the nodes added. Will be an empty <code>NodeList</code> if no nodes were added.</td> + </tr> + <tr> + <td><code>removedNodes</code></td> + <td><code>{{domxref("NodeList")}}</code></td> + <td>Return the nodes removed. Will be an empty <code>NodeList</code> if no nodes were removed.</td> + </tr> + <tr> + <td><code>previousSibling</code></td> + <td><code>{{domxref("Node")}}</code></td> + <td>Return the previous sibling of the added or removed nodes, or <code>null</code>.</td> + </tr> + <tr> + <td><code>nextSibling</code></td> + <td><code>{{domxref("Node")}}</code></td> + <td>Return the next sibling of the added or removed nodes, or <code>null</code>.</td> + </tr> + <tr> + <td><code>attributeName</code></td> + <td><code>String</code></td> + <td>Returns the local name of the changed attribute, or <code>null</code>.</td> + </tr> + <tr> + <td><code>attributeNamespace</code></td> + <td><code>String</code></td> + <td>Returns the namespace of the changed attribute, or <code>null</code>.</td> + </tr> + <tr> + <td><code>oldValue</code></td> + <td><code>String</code></td> + <td>The return value depends on the <code>type</code>. For <code>attributes</code>, it is the value of the changed attribute before the change. For <code>characterData</code>, it is the data of the changed node before the change. For <code>childList</code>, it is <code>null</code>.</td> + </tr> + </tbody> +</table> + +<h2 id="Example_usage">Example usage</h2> + +<p>The following example was taken from <a class="external" href="http://hacks.mozilla.org/2012/05/dom-mutationobserver-reacting-to-dom-changes-without-killing-browser-performance/" rel="freelink">this blog post</a>.</p> + +<pre class="brush: js">// select the target node +var target = document.querySelector('#some-id'); + +// create an observer instance +var observer = new MutationObserver(function(mutations) { + mutations.forEach(function(mutation) { + console.log(mutation.type); + }); +}); + +// configuration of the observer: +var config = { attributes: true, childList: true, characterData: true }; + +// pass in the target node, as well as the observer options +observer.observe(target, config); + +// later, you can stop observing +observer.disconnect(); +</pre> + +<h2 id="Additional_reading">Additional reading</h2> + +<ul> + <li><a class="external" href="http://updates.html5rocks.com/2012/02/Detect-DOM-changes-with-Mutation-Observers" rel="freelink">A brief overview</a></li> + <li><a class="external" href="http://hacks.mozilla.org/2012/05/dom-mutationobserver-reacting-to-dom-changes-without-killing-browser-performance/" rel="freelink">A more in-depth discussion</a></li> + <li><a class="external" href="http://www.youtube.com/watch?v=eRZ4pO0gVWw" rel="freelink">A screencast by Chromium developer Rafael Weinstein</a></li> + <li><a class="external" href="http://code.google.com/p/mutation-summary/" rel="freelink">The mutation summary library</a></li> + <li><a href="http://dom.spec.whatwg.org/#mutation-observers">The DOM standard</a> which defines the <code>MutationObserver</code> interface</li> +</ul> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{CompatibilityTable}}</p> + +<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>18 {{property_prefix("-webkit")}}<br> + 26</td> + <td>{{CompatGeckoDesktop(14)}}</td> + <td>11</td> + <td>15</td> + <td>6.0 {{property_prefix("-webkit")}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>18 {{property_prefix("-webkit")}}<br> + 26</td> + <td>{{CompatGeckoMobile(14)}}</td> + <td>11 (8.1)</td> + <td>15</td> + <td>6 {{property_prefix("-webkit")}}<br> + 7</td> + </tr> + </tbody> +</table> +</div> diff --git a/files/zh-tw/web/api/namednodemap/index.html b/files/zh-tw/web/api/namednodemap/index.html new file mode 100644 index 0000000000..1aafe72d0a --- /dev/null +++ b/files/zh-tw/web/api/namednodemap/index.html @@ -0,0 +1,156 @@ +--- +title: NamedNodeMap +slug: Web/API/NamedNodeMap +translation_of: Web/API/NamedNodeMap +--- +<div>{{APIRef("DOM")}}</div> + +<p><code><strong>NamedNodeMap</strong></code> 介面表示了 {{domxref("Attr")}} 物件的集合。雖然 <code>NamedNodeMap</code> 與 {{domxref("NodeList")}} 都能如陣列一般透過索引訪問成員，但和 <code>NodeList</code> 不同的是，<code>NamedNodeMap</code> 中的成員並沒有順序。</p> + +<p><code>NamedNodeMap</code> 物件具有<em>即時性（live）</em>，如果其內部成員（屬性節點物件）發生改變，<code>NamedNodeMap</code> 物件會自動更新至最新的狀態。</p> + +<div class="note"> +<p>僅管被稱作 <code>NamedNodeMap</code>，但本介面並不是直接用來處理節點物件（{{domxref("Node")}}），而是專門負責屬性節點物件（{{domxref("Attr")}}）。屬性節點是一種特殊的節點，在部分瀏覽器實作中依然存在。</p> +</div> + +<h2 id="屬性">屬性</h2> + +<p><em>This interface doesn't inherit any property.</em></p> + +<dl> + <dt>{{domxref("NamedNodeMap.length")}} {{ReadOnlyInline}}</dt> + <dd>Returns the amount of objects in the map.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>This interface doesn't inherit any method.</em></p> + +<dl> + <dt>{{domxref("NamedNodeMap.getNamedItem()")}}</dt> + <dd>Returns a {{domxref("Attr")}}, corresponding to the given name.</dd> + <dt>{{domxref("NamedNodeMap.setNamedItem()")}}</dt> + <dd>Replaces, or adds, the {{domxref("Attr")}} identified in the map by the given name.</dd> + <dt>{{domxref("NamedNodeMap.removeNamedItem()")}}</dt> + <dd>Removes the {{domxref("Attr")}} identified by the given map.</dd> + <dt>{{domxref("NamedNodeMap.item()")}}</dt> + <dd>Returns the {{domxref("Attr")}} at the given index, or <code>null</code> if the index is higher or equal to the number of nodes.</dd> + <dt>{{domxref("NamedNodeMap.getNamedItemNS()")}}</dt> + <dd>Returns a {{domxref("Attr")}} identified by a namespace and related local name.</dd> + <dt>{{domxref("NamedNodeMap.setNamedItemNS()")}}</dt> + <dd>Replaces, or adds, the {{domxref("Attr")}} identified in the map by the given namespace and related local name.</dd> + <dt>{{domxref("NamedNodeMap.removeNamedItemNS()")}}</dt> + <dd>Removes the {{domxref("Attr")}} identified by the given namespace and related local name.</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('DOM WHATWG', '#interface-namednodemap', 'NamedNodeMap')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>Deals with {{domxref("Attr")}} instead of {{domxref("Node")}}</td> + </tr> + <tr> + <td>{{SpecName('DOM3 Core', 'core.html#ID-1780488922', 'NamedNodeMap')}}</td> + <td>{{Spec2('DOM3 Core')}}</td> + <td>No change from {{SpecName('DOM2 Core')}}</td> + </tr> + <tr> + <td>{{SpecName('DOM2 Core', 'core.html#ID-1780488922', 'NamedNodeMap')}}</td> + <td>{{Spec2('DOM2 Core')}}</td> + <td>Added <code>getNamedItemNS()</code>, <code>setNamedItemNS()</code> and <code>removeNamedItemNS()</code></td> + </tr> + <tr> + <td>{{SpecName('DOM1', 'core.html#ID-1780488922', 'NamedNodeMap')}}</td> + <td>{{Spec2('DOM1')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>Deals with {{domxref("Attr")}} rather than {{domxref("Node")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoDesktop(22)}}<sup>[1]</sup></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>Deals with {{domxref("Attr")}} rather than {{domxref("Node")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile(22)}}<sup>[1]</sup></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] In Gecko 22 this interface was named <code>mozNamedAttrMap</code>. In Gecko 34 it was named back to <code>NamedNodeMap</code>.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("Element.attributes")}}</li> +</ul> diff --git a/files/zh-tw/web/api/navigator/geolocation/index.html b/files/zh-tw/web/api/navigator/geolocation/index.html new file mode 100644 index 0000000000..7c709b0b21 --- /dev/null +++ b/files/zh-tw/web/api/navigator/geolocation/index.html @@ -0,0 +1,96 @@ +--- +title: Navigator.geolocation +slug: Web/API/Navigator/geolocation +translation_of: Web/API/Navigator/geolocation +--- +<div>{{APIRef("Geolocation API")}}</div> + +<p><strong><code>Navigator.geolocation</code></strong> 回傳一個唯讀的 {{domxref("Geolocation")}} 物件，透過這個物件可以存取設備的位置訊息。同時也允許網站或應用程式根據使用者的位置提供客製化的結果。</p> + +<div class="note"> +<p><strong>備註:</strong> 因為隱私的因素，當網頁要求存取位置資訊時，用戶會被提示通知並且詢問授權與否。注意不同的瀏覽器在詢問授權時有各自不同的策略和方式。</p> +</div> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><var>geo</var> = <var>navigator</var>.geolocation +</pre> + +<h2 id="規格">規格</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('Geolocation', '#navi-geo', 'Navigator.geolocation')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + {{CompatNo}} 15.0<br> + 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown}}</td> + <td>10.60</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> +</ul> diff --git a/files/zh-tw/web/api/navigator/index.html b/files/zh-tw/web/api/navigator/index.html new file mode 100644 index 0000000000..84fcfacf61 --- /dev/null +++ b/files/zh-tw/web/api/navigator/index.html @@ -0,0 +1,154 @@ +--- +title: Navigator +slug: Web/API/Navigator +tags: + - API + - HTML-DOM + - Interface + - NeedsTranslation + - Reference + - TopicStub + - Web Performance +translation_of: Web/API/Navigator +--- +<p>{{ APIRef("DOM4") }}</p> + +<p><code><strong>Navigator</strong></code> 介面標示了用戶代理（user agent）的狀態與身份。它允許腳本查詢與註冊，以進行一些活動。</p> + +<p><code>Navigator</code> 可以被檢索，只要使用唯讀的 {{domxref("window.navigator")}} 屬性。</p> + +<h2 id="屬性">屬性</h2> + +<p><em>它並不繼承任何屬性，但其實做已被定義於 {{domxref("NavigatorID")}}、{{domxref("NavigatorLanguage")}}、{{domxref("NavigatorOnLine")}}、{{domxref("NavigatorContentUtils")}}、{{domxref("NavigatorStorage")}}、{{domxref("NavigatorStorageUtils")}}、{{domxref("NavigatorConcurrentHardware")}}、{{domxref("NavigatorPlugins")}}、{{domxref("NavigatorUserMedia")}}.</em></p> + +<h3 id="標準">標準</h3> + +<dl> + <dt>{{domxref("Navigator.activeVRDisplays")}} {{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns an array containing every {{domxref("VRDisplay")}} object that is currently presenting ({{domxref("VRDisplay.ispresenting")}} is <code>true</code>).</dd> + <dt>{{domxref("NavigatorID.appCodeName")}} {{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns the internal "code" name of the current browser. Do not rely on this property to return the correct value.</dd> + <dt>{{domxref("NavigatorID.appName")}} {{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns a {{domxref("DOMString")}} with the official name of the browser. Do not rely on this property to return the correct value.</dd> + <dt>{{domxref("NavigatorID.appVersion")}} {{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns the version of the browser as a {{domxref("DOMString")}}. Do not rely on this property to return the correct value.</dd> + <dt>{{domxref("Navigator.battery")}} {{readonlyInline}}</dt> + <dd>Returns a {{domxref("BatteryManager")}} object you can use to get information about the battery charging status.</dd> + <dt>{{domxref("Navigator.connection")}} {{readonlyInline}}{{experimental_inline}}</dt> + <dd>Provides a {{domxref("NetworkInformation")}} object containing information about the network connection of a device.</dd> + <dt>{{domxref("Navigator.cookieEnabled")}} {{readonlyinline}}</dt> + <dd>Returns false if setting a cookie will be ignored and true otherwise.</dd> + <dt>{{domxref("Navigator.geolocation")}} {{readonlyInline}}</dt> + <dd>Returns a {{domxref("Geolocation")}} object allowing accessing the location of the device.</dd> + <dt>{{domxref("NavigatorConcurrentHardware.hardwareConcurrency")}} {{readOnlyInline}}</dt> + <dd>Returns the number of logical processor cores available.</dd> + <dt>{{domxref("NavigatorPlugins.javaEnabled")}} {{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns a {{domxref("Boolean")}} flag indicating whether the host browser is Java-enabled or not.</dd> + <dt>{{domxref("NavigatorLanguage.language")}} {{readonlyInline}}</dt> + <dd>Returns a {{domxref("DOMString")}} representing the preferred language of the user, usually the language of the browser UI. The <code>null</code> value is returned when this is unknown.</dd> + <dt>{{domxref("NavigatorLanguage.languages")}} {{readonlyInline}}</dt> + <dd>Returns an array of {{domxref("DOMString")}} representing the languages known to the user, by order of preference.</dd> + <dt>{{domxref("NavigatorPlugins.mimeTypes")}} {{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns an {{domxref("MimeTypeArray")}} listing the MIME types supported by the browser.</dd> + <dt>{{domxref("NavigatorOnLine.onLine")}} {{readonlyInline}}</dt> + <dd>Returns a {{domxref("Boolean")}} indicating whether the browser is working online.</dd> + <dt>{{domxref("Navigator.oscpu")}}</dt> + <dd>Returns a string that represents the current operating system.</dd> + <dt>{{domxref("Navigator.permissions")}} {{readonlyinline}}{{experimental_inline}}</dt> + <dd>Returns a {{domxref("Permissions")}} object that can be used to query and update permission status of APIs covered by the <a href="/en-US/docs/Web/API/Permissions_API">Permissions API</a>.</dd> + <dt>{{domxref("NavigatorID.platform")}} {{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns a string representing the platform of the browser. Do not rely on this function to return a significant value.</dd> + <dt>{{domxref("NavigatorPlugins.plugins")}} {{readonlyInline}}{{experimental_inline}}</dt> + <dd>Returns a {{domxref("PluginArray")}} listing the plugins installed in the browser.</dd> + <dt>{{domxref("NavigatorID.product")}} {{readonlyInline}} {{experimental_inline}}</dt> + <dd>Always returns <code>'Gecko'</code>, on any browser. This property is kept only for compatibility purpose.</dd> + <dt>{{domxref("Navigator.serviceWorker")}} {{readonlyInline}}</dt> + <dd>Returns a {{domxref("ServiceWorkerContainer")}} object, which provides access to registration, removal, upgrade, and communication with the {{domxref("ServiceWorker")}} objects for the <a href="https://html.spec.whatwg.org/multipage/browsers.html#concept-document-window">associated document</a>.</dd> + <dt>{{domxref("Navigator.storage")}} {{readonlyinline}}</dt> + <dd>Returns the singleton {{domxref('StorageManager')}} object used for managing persistance permissions and estimating available storage on a site-by-site/app-by-app basis.</dd> + <dt>{{domxref("NavigatorID.userAgent")}} {{readonlyInline}}</dt> + <dd>Returns the user agent string for the current browser.</dd> +</dl> + +<h3 id="Methods" name="Methods">Non-standard</h3> + +<div class="note"> +<p>Firefox OS devices adds more non-standard properties. You can consult them on the <a href="/en-US/docs/Mozilla/Firefox_OS/API/Navigator">Firefox OS Navigator extensions article</a>.</p> +</div> + + <dl> + <dt>{{domxref("Navigator.buildID")}} {{non-standard_inline}}</dt> + <dd>Returns the build identifier of the browser (e.g., "2006090803").</dd> + <dt>{{domxref("Navigator.cookieEnabled")}} {{non-standard_inline}}</dt> + <dd>Returns a boolean indicating whether cookies are enabled in the browser or not.</dd> + <dt>{{domxref("Navigator.credentials")}} {{non-standard_inline}}</dt> + <dd>Returns the {{domxref("CredentialsContainer")}} interface which exposes methods to request credentials and notify the user agent when interesting events occur such as successful sign in or sign out. </dd> + <dt>{{domxref("Navigator.doNotTrack")}} {{non-standard_inline}}</dt> + <dd>Reports the value of the user's do-not-track preference. When this value is "yes", your web site or application should not track the user.</dd> + <dt>{{domxref("Navigator.id")}} {{non-standard_inline}}</dt> + <dd>Returns the {{domxref("window.navigator.id", "id")}} object which you can use to add support for <a href="/en-US/docs/BrowserID" title="BrowserID">BrowserID</a> to your web site.</dd> + <dt>{{domxref("Navigator.mediaDevices")}} {{non-standard_inline}}</dt> + <dd>Returns a reference to a {{domxref("MediaDevices")}} object which can then be used to get information about available media devices ({{domxref("MediaDevices.enumerateDevices()")}}), find out what constrainable properties are supported for media on the user's computer and user agent ({{domxref("MediaDevices.getSupportedConstraints()")}}), and to request access to media using {{domxref("MediaDevices.getUserMedia()")}}.</dd> + <dt>{{domxref("Navigator.mozNotification")}} {{deprecated_inline("22")}} {{non-standard_inline}}<br> + {{domxref("Navigator.webkitNotification")}}</dt> + <dd>Returns a {{domxref("navigator.mozNotification", "notification")}} object you can use to deliver notifications to the user from your web application.</dd> + <dt>{{domxref("Navigator.mozSocial")}} {{non-standard_inline}}</dt> + <dd>The Object, returned by the <code>navigator.mozSocial</code> property, is available within the social media provider's panel to provide functionality it may need.</dd> + <dt>{{domxref("Navigator.presentation")}} {{non-standard_inline}}</dt> + <dd>Returns a reference to the {{domxref("Presentation")}} API.</dd> + <dt>{{domxref("Navigator.productSub")}} {{non-standard_inline}}</dt> + <dd>Returns the build number of the current browser (e.g., "20060909").</dd> + <dt>{{domxref("Navigator.securitypolicy")}} {{non-standard_inline}}</dt> + <dd>Returns an empty string. In Netscape 4.7x, returns "US & CA domestic policy" or "Export policy".</dd> + <dt>{{domxref("Navigator.standalone")}} {{non-standard_inline}}</dt> + <dd>Returns a boolean indicating whether the browser is running in standalone mode. Available on Apple's iOS Safari only.</dd> + <dt>{{domxref("Navigator.storageQuota")}} {{readonlyinline}} {{experimental_inline}}</dt> + <dd>Returns a {{domxref('StorageQuota')}} interface which provides means to query and request storage usage and quota information.</dd> + <dt>{{domxref("Navigator.vendor")}} {{non-standard_inline}}</dt> + <dd>Returns the vendor name of the current browser (e.g., "Netscape6").</dd> + <dt>{{domxref("Navigator.vendorSub")}} {{non-standard_inline}}</dt> + <dd>Returns the vendor version number (e.g. "6.1").</dd> + <dt>{{domxref("Navigator.webkitPointer")}} {{non-standard_inline}}</dt> + <dd>Returns a PointerLock object for the <a href="/en-US/docs/API/Pointer_Lock_API" title="Mouse Lock API">Mouse Lock API</a>.</dd> +</dl> + +<h2 id="Methods" name="Methods">方法</h2> + +<p><em>Doesn't inherit any method, but implements those defined in {{domxref("NavigatorID")}}, {{domxref("NavigatorContentUtils")}}, <em>{{domxref("NavigatorUserMedia")}}, </em>and {{domxref("NavigatorStorageUtils")}}.</em></p> + +<h3 id="Standard">Standard</h3> + +<dl> + <dt>{{domxref("Navigator.getVRDisplays()")}} {{experimental_inline}}</dt> + <dd>Returns a promise that resolves to an array of {{domxref("VRDisplay")}} objects representing any available VR devices connected to the computer.</dd> + <dt>{{domxref("Navigator.getUserMedia", "Navigator.getUserMedia()")}} {{experimental_inline}}</dt> + <dd>After having prompted the user for permission, returns the audio or video stream associated to a camera or microphone on the local computer.</dd> + <dt>{{domxref("Navigator.registerContentHandler()")}}</dt> + <dd>Allows web sites to register themselves as a possible handler for a given MIME type.</dd> + <dt>{{domxref("Navigator.registerProtocolHandler()")}}</dt> + <dd>Allows web sites to register themselves as a possible handler for a given protocol.</dd> + <dt>{{domxref("Navigator.requestMediaKeySystemAccess()")}} {{experimental_inline}}</dt> + <dd>Returns a <span style="line-height: 19.0909080505371px;">{{jsxref("Promise")}} for a MediaKeySystemAccess object.</span></dd> + <dt>{{domxref("Navigator.sendBeacon()")}}{{experimental_inline}}</dt> + <dd>Used to asynchronously transfer a small amount of data using {{Glossary("HTTP")}} from the User Agent to a web server.</dd> + <dt>{{domxref("Navigator.share()")}}{{experimental_inline}}</dt> + <dd>Invokes the native sharing mechanism of the current platform.</dd> + <dt>{{domxref("NavigatorID.taintEnabled()")}} {{deprecated_inline("1.7.8")}} {{obsolete_inline("9.0")}} {{experimental_inline}}</dt> + <dd>Returns <code>false</code>. JavaScript taint/untaint functions removed in JavaScript 1.2.</dd> + <dt>{{domxref("Navigator.vibrate()")}} {{gecko_minversion_inline("11.0")}}</dt> + <dd>Causes vibration on devices with support for it. Does nothing if vibration support isn't available.</dd> +</dl> + +<h3 id="Specification" name="Specification">Non-standard</h3> + +<div class="note"> +<p>Firefox OS devices adds more non-standard methods. You can consult them on the <a href="/en-US/docs/Mozilla/Firefox_OS/API/Navigator">Firefox OS Navigator extensions article</a>.</p> +</div> + +<p>{{domxref("Navigator.mozIsLocallyAvailable()")}} {{non-standard_inline}}</p> + +<dl> + <dd>Lets code check to see if the document at a given URI is available without using the network.</dd> + <dt>{{domxref("Navigator.mozPay()")}} {{non-standard_inline}}</dt> + <dd>Allows in-app payment.</dd> +</dl> diff --git a/files/zh-tw/web/api/navigator/registerprotocolhandler/index.html b/files/zh-tw/web/api/navigator/registerprotocolhandler/index.html new file mode 100644 index 0000000000..2ffd20da9d --- /dev/null +++ b/files/zh-tw/web/api/navigator/registerprotocolhandler/index.html @@ -0,0 +1,170 @@ +--- +title: Navigator.registerProtocolHandler() +slug: Web/API/Navigator/registerProtocolHandler +translation_of: Web/API/Navigator/registerProtocolHandler +--- +<div>{{APIRef("HTML DOM")}}</div> + +<p>In progress. Allows web sites to register themselves as possible handlers for particular protocols.</p> + +<p>For security reasons, by default, web sites may only register protocol handlers for themselves — the domain and protocol of the handler must match the current site. However, users may set a preference in Firefox to allow cross website installation, by setting the <code>gecko.handlerService.allowRegisterFromDifferentHost</code> pref to <code>true</code> in about:config.</p> + +<p>Extensions can register protocol handlers targeting other sites: see the 'See Also' section for how to use them from XPCOM.</p> + +<h2 id="Syntax">Syntax</h2> + +<pre class="syntaxbox">window.navigator.registerProtocolHandler(<em>protocol</em>, <em>url</em>, <em>title</em>); +</pre> + +<h3 id="Parameters">Parameters</h3> + +<dl> + <dt><code>protocol</code></dt> + <dd>The protocol the site wishes to handle, specified as a string. For example, you can register to handle SMS text message links by registering to handle the "sms" scheme.</dd> + <dt><code>url</code></dt> + <dd>The URL of the handler, as a string. This string should include "%s" as a placeholder which will be replaced with the escaped URL of the document to be handled. This URL might be a true URL, or it could be a phone number, email address, or so forth. + <div class="note">The handler's URL must use one of "http" or "https" as its scheme.</div> + </dd> + <dt><code>title</code></dt> + <dd>A user-readable title string for the protocol handler. This will be displayed to the user in interface objects as needed.</dd> +</dl> + +<h3 id="Exceptions">Exceptions</h3> + +<dl> + <dt><code>SecurityError</code></dt> + <dd>The user agent blocked registration of the protocol handler. This might happen if an invalid scheme is specified, such as "http", which cannot be registered for obvious security reasons.</dd> + <dt><code>SyntaxError</code></dt> + <dd>The "%s" string is missing from the specified protocol handler URL.</dd> +</dl> + +<h2 id="Permitted_schemes">Permitted schemes</h2> + +<p>For security reasons, <code>registerProtocolHandler()</code> has restrictions on which schemes may be registered. A custom scheme may be registered as long as the scheme's name begins with "web+", is at least five characters long (including the "web+" prefix), and has only lower-case ASCII letters in its name. For example, "web+burger", as shown in the {{anch("Example")}} below.</p> + +<p>Otherwise, the scheme must be one of the schemes on the whitelist below:</p> + +<div class="threecolumns"> +<ul> + <li><code>bitcoin</code></li> + <li><code>geo</code></li> + <li><code>im</code></li> + <li><code>irc</code></li> + <li><code>ircs</code></li> + <li><code>magnet</code></li> + <li><code>mailto</code></li> + <li><code>mms</code></li> + <li><code>news</code></li> + <li><code>nntp</code></li> + <li><code>sip</code></li> + <li><code>sms</code></li> + <li><code>smsto</code></li> + <li><code>ssh</code></li> + <li><code>tel</code></li> + <li><code>urn</code></li> + <li><code>webcal</code></li> + <li><code>wtai</code></li> + <li><code>xmpp</code></li> +</ul> +</div> + +<h2 id="Example">Example</h2> + +<p>If your web application is located at <code>http://www.google.co.uk</code>, you can register a protocol handler for it to handle "web+burger" links like this:</p> + +<pre class="brush: js">navigator.registerProtocolHandler("web+burger", + "https://www.google.co.uk/?uri=%s", + "Burger handler"); +</pre> + +<p>This creates a handler that allows <code>web+burger://</code> links to direct the user to your web application, inserting the burger information specified in the link into the URL. Recall that this script must be run from the same domain (so any page location at <code>google.co.uk</code>) and the second argument passed must be of <code>http</code> or <code>https</code> scheme (in this example it is <code>https</code>) .</p> + +<p>The user will be notified that your code has asked to register the protocol handler, so that they can decide whether or not to permit it. See the screenshot below for an example.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/9683/protocolregister.png"></p> + +<div class="note"> +<p>"<a href="/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIWebContentHandlerRegistrar#Getting_most_recent_window">Register a webmail service as mailto handler</a>" shows how to do this from XPCOM scope.</p> +</div> + +<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', 'webappapis.html#dom-navigator-registerprotocolhandler', 'registerProtocolHandler()')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{CompatibilityTable}}</p> + +<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>13<sup>[1]</sup></td> + <td>{{CompatGeckoDesktop("1.9")}}</td> + <td>{{CompatUnknown}}</td> + <td>11.60</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("3.5")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Protocol whitelist includes <code>mailto</code>, <code>mms</code>, <code>nntp</code>, <code>rtsp</code>, and <code>webcal</code>. Custom protocols must be prefixed with <code>web+</code>.</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/Web-based_protocol_handlers">Web-based protocol handlers</a></li> + <li><a href="/en-US/docs/Web/API/Navigator/registerContentHandler">Navigator.registerContentHandler()</a></li> + <li><a href="http://blog.mozilla.com/webdev/2010/07/26/registerprotocolhandler-enhancing-the-federated-web/">RegisterProtocolHandler Enhancing the Federated Web</a> at Mozilla Webdev</li> + <li><a href="https://html.spec.whatwg.org/multipage/system-state.html#custom-handlers">Web Application APIs - Custom scheme and content handlers</a></li> + <li><a href="/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIWebContentHandlerRegistrar#Getting_most_recent_window">Register a webmail service as mailto handler</a> shows how to do <code>registerProtocolHandler</code> from XPCOM scope.</li> + <li><a href="/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIWebContentHandlerRegistrar#registerProtocolHandler">XPCOM Interface Reference > nsIWebContentHandlerRegistrar > registerContentHandler</a> - This shows how to use this function XPCOM scope</li> +</ul> diff --git a/files/zh-tw/web/api/navigator/registerprotocolhandler/web-based_protocol_handlers/index.html b/files/zh-tw/web/api/navigator/registerprotocolhandler/web-based_protocol_handlers/index.html new file mode 100644 index 0000000000..f32ac8ca88 --- /dev/null +++ b/files/zh-tw/web/api/navigator/registerprotocolhandler/web-based_protocol_handlers/index.html @@ -0,0 +1,28 @@ +--- +title: Firefox 3 Web-based protocol handler +slug: Web/API/Navigator/registerProtocolHandler/Web-based_protocol_handlers +translation_of: Web/API/Navigator/registerProtocolHandler/Web-based_protocol_handlers +--- +<h3 id=".E6.91.98.E8.A6.81" name=".E6.91.98.E8.A6.81">摘要</h3> +<p>window.navigator.registerProtocolHandler 讓網站可以將自己註冊為特定通訊協定的處理者。</p> +<h3 id=".E8.AA.9E.E6.B3.95" name=".E8.AA.9E.E6.B3.95">語法</h3> +<pre>window.navigator.registerProtocolHandler(protocol, uri, title);</pre> +<ul> + <li>protocol 是網站想要處理的 protocol 名稱，用字串表示。</li> + <li>uri 是要給 handler 處理的 URI 字串。你可以在字串裡用 "%s" 來代表 escaped 過、需要處理的 URI。</li> + <li>title 是 handler 的 title，會以字串的形式呈現給使用者。</li> +</ul> +<h3 id=".E4.BE.8B.E5.AD.90" name=".E4.BE.8B.E5.AD.90">例子</h3> +<pre>navigator.registerProtocolHandler("mailto", + "https://mail.google.com/mail?view=cm&tf=0&to=%s", + "Google Mail"); +</pre> +<p>這會建立一個 handler，它允許 mailto 的鏈結將使用者帶到 Google Mail，將鏈結中指定的 email 位址插入到 URL。</p> +<h3 id=".E5.8F.83.E8.80.83.E8.B3.87.E6.96.99" name=".E5.8F.83.E8.80.83.E8.B3.87.E6.96.99">參考資料</h3> +<ol> + <li><a class="external" href="http://developer.mozilla.org/en/docs/DOM:window.navigator.registerProtocolHandler">DOM:window.navigator.registerProtocolHandler 原始網頁</a></li> +</ol> +<h3 id=".E5.BB.B6.E4.BC.B8.E9.96.B1.E8.AE.80" name=".E5.BB.B6.E4.BC.B8.E9.96.B1.E8.AE.80">延伸閱讀</h3> +<ol> + <li>WHATWG's <a class="external" href="http://whatwg.org/specs/web-apps/current-work/#custom-handlers">Web Applications 1.0 working draft</a></li> +</ol> diff --git a/files/zh-tw/web/api/navigatoronline/index.html b/files/zh-tw/web/api/navigatoronline/index.html new file mode 100644 index 0000000000..6e6eafaa48 --- /dev/null +++ b/files/zh-tw/web/api/navigatoronline/index.html @@ -0,0 +1,129 @@ +--- +title: NavigatorOnLine +slug: Web/API/NavigatorOnLine +translation_of: Web/API/NavigatorOnLine +--- +<p>{{APIRef("HTML DOM")}}</p> + +<p>In progress The <code><strong>NavigatorOnLine</strong></code> interface contains methods and properties related to the connectivity status of the browser.</p> + +<p>There is no object of type <code>NavigatorOnLine</code>, but other interfaces, like {{domxref("Navigator")}} or {{domxref("WorkerNavigator")}}, implement it.</p> + +<h2 id="Properties">Properties</h2> + +<p><em>The <code>NavigatorOnLine</code></em><em> interface doesn't inherit any property.</em></p> + +<dl> + <dt>{{domxref("NavigatorOnLine.onLine")}} {{readonlyInline}}</dt> + <dd>Returns a {{domxref("Boolean")}} indicating whether the browser is working online.</dd> +</dl> + +<h2 id="Methods">Methods</h2> + +<p><em>The </em><em><code>NavigatorOnLine</code></em><em> interface neither implements, nor inherit any method.</em></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', '#navigatoronline', 'NavigatorOnLine')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>No change from the latest snapshot, {{SpecName('HTML5 W3C')}}</td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', '#navigatoronline', 'NavigatorOnLine')}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>Snapshot of {{SpecName('HTML WHATWG')}} with its initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>on {{domxref("WorkerNavigator")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoDesktop(29)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>on {{domxref("WorkerNavigator")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile(29)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="See_also">See also</h2> + +<ul> + <li>The {{domxref("Navigator")}} interface that implements it.</li> + <li><a href="/en-US/docs/Web/API/NavigatorOnLine/Online_and_offline_events">Online and offline events</a></li> +</ul> diff --git a/files/zh-tw/web/api/navigatoronline/online_and_offline_events/index.html b/files/zh-tw/web/api/navigatoronline/online_and_offline_events/index.html new file mode 100644 index 0000000000..c8bf629d8c --- /dev/null +++ b/files/zh-tw/web/api/navigatoronline/online_and_offline_events/index.html @@ -0,0 +1,101 @@ +--- +title: Firefox 3 Online and Offline Events +slug: Web/API/NavigatorOnLine/Online_and_offline_events +translation_of: Web/API/NavigatorOnLine/Online_and_offline_events +--- +<p>Firefox 3 Online and Offline Events From MoztwWiki</p> +<p>Firefox 3 依據 <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/">WHATWG Web Applications 1.0 Specification</a> 實做了 <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/#offline">Offline/Online Events</a>。</p> +<h3 id=".E6.A6.82.E8.A7.80" name=".E6.A6.82.E8.A7.80">概觀</h3> +<p>打造可以離線跑的網路應用程式時，我們往往需要讓程式知道目前的網路狀況。實際上，網路應用程式一般的需求可細分如下：</p> +<ul> + <li>使用者連上網路的時候，網路應用程式必須知道—使用者已經連上網路了，以便與伺服器同步(re-synchronize)。</li> + <li>使用者離線的時候，網路應用程式必須知道—使用者目前處於離線狀態，以便將使用者對伺服器發出的 requests 排入隊列(queue)。</li> +</ul> +<p>有了 Online/offline events，要滿足這些需求變得很簡單。</p> +<p>此外，你的網路應用程式有時可能必須將某些 HTML 文件列入快取中，以便使用者離線時可以存取，如有這個需求，你可以在 HTML 文件的 <HEAD> 加入 <link> 元素：</p> +<pre><link rel="offline-resource" href="myresource"></pre> +<p>Firefox 3 看到這些語法時，就會將這些資源列入一個特殊的離線資源快取(offline resource cache)中，讓使用者在離線時，依舊可以被存取這些資源。</p> +<h3 id="API" name="API">API</h3> +<h4 id="navigator.onLine" name="navigator.onLine">navigator.onLine</h4> +<dl> + <dd> + avigator.onLine 是一個 property，其值可為 true/false (true 代表 online, false 代表 offline)。當使用者將瀏覽器切換成 Offline Mode 時(透過 主選單 -> 檔案 -> 離線模式)，這個 property 就會被更新。</dd> +</dl> +<dl> + <dd> + 除此之外，根據規格書的建議，在瀏覽器無法連接到網路時，也應該更新這個 property。規格書上是這樣寫的：</dd> + <dd> + <blockquote> + The navigator.onLine attribute must return false if the user agent will not contact the network when the user follows links or when a script requests a remote page (or knows that such an attempt would fail)...</blockquote> + </dd> +</dl> +<dl> + <dd> + Firefox 2 在我們將瀏覽器切換成為離線模式、或離開離線模式時，會更新這個 property，在失去網路連線、或重新連線到網路時，也會更新這個 property。</dd> +</dl> +<dl> + <dd> + 在比較老的 Firefox 與 Internet Explorer 版本，也有支援這個 property (事實上，規格書是依據這些之前版本的實做結果來制定的)，所以現在就可以馬上開始使用它。</dd> +</dl> +<dl> + <dd> + 但「自動偵測網路狀況」是在 Firefox 2 中才實做出來。</dd> +</dl> +<h4 id="online_and_offline_events" name="online_and_offline_events">online and offline events</h4> +<dl> + <dd> + Firefox 3 新增了兩個 events 的支援： "online" 及 "offline"。當我們切換瀏覽器的 online/offline 狀態時，就會對每個頁面的 <body> 觸發這兩個事件。除此之外，這兩個事件會從 document.body bubble up 到 document，到 window 才結束。這兩個事件都是 non-cancellable 的(因為你無法防止使用者連線到網路、或離線)。</dd> +</dl> +<dl> + <dd> + 有好幾種你熟悉的方式可以用來註冊這兩個事件的 listeners：</dd> +</dl> +<dl> + <dd> + <ul> + <li>對 window, document 或 document.body 使用 addEventListener。</li> + <li>對 document 或 document.body 設定 .ononline 或 .onoffline properties 作為一個 JavaScript Function object. (注意： 使用 window.ononline 或 window.onoffline 無法作用，這是為了相容性。)</li> + <li>在 html 文件的 <body> 指定 ononline="..." 或 onoffline="..." attributes。</li> + </ul> + </dd> +</dl> +<h3 id=".E4.BE.8B.E5.AD.90" name=".E4.BE.8B.E5.AD.90">例子</h3> +<p>這裡有個<a class="link-https" href="https://bugzilla.mozilla.org/attachment.cgi?id=220609">簡單的例子</a>。</p> +<pre><!doctype html> + <html> + <head> + <script> + function updateOnlineStatus(msg) { + var status = document.getElementById("status"); + var condition = navigator.onLine ? "ONLINE" : "OFFLINE"; + status.setAttribute("class", condition); + var state = document.getElementById("state"); + state.innerHTML = condition; + var log = document.getElementById("log"); + log.appendChild(document.createTextNode("Event: " + msg + "; status=" + condition + "\n")); + } + function loaded() { + updateOnlineStatus("load"); + document.body.addEventListener("offline", function () { + updateOnlineStatus("offline") + }, false); + document.body.addEventListener("online", function () { + updateOnlineStatus("online") + }, false); + } + </script> + <style>...</style> + </head> + <body onload="loaded()"> + <div id="status"><p id="state"></p></div> + <div id="log"></div> + </body> + </html></pre> +<h3 id=".E5.8F.83.E8.80.83.E8.B3.87.E6.96.99" name=".E5.8F.83.E8.80.83.E8.B3.87.E6.96.99">參考資料</h3> +<ul> + <li><a class="external" href="http://developer.mozilla.org/en/docs/Online_and_offline_events">Online and Offline Events 原始網頁</a></li> + <li><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/#offline">'Online/Offline events' section from the WHATWG Web Applications 1.0 Specification</a></li> + <li><a class="link-https" href="https://bugzilla.mozilla.org/show_bug.cgi?id=336359">The bug tracking online/offline events implementation in Firefox</a> and <a class="link-https" href="https://bugzilla.mozilla.org/show_bug.cgi?id=336682">Follow-up</a></li> + <li><a class="link-https" href="https://bugzilla.mozilla.org/attachment.cgi?id=220609">一個簡單的例子</a></li> + <li><a class="external" href="http://ejohn.org/blog/offline-events/">An explanation of Online/Offline events</a></li> +</ul> diff --git a/files/zh-tw/web/api/network_information_api/index.html b/files/zh-tw/web/api/network_information_api/index.html new file mode 100644 index 0000000000..c7f24856a4 --- /dev/null +++ b/files/zh-tw/web/api/network_information_api/index.html @@ -0,0 +1,46 @@ +--- +title: Network Information API +slug: Web/API/Network_Information_API +translation_of: Web/API/Network_Information_API +--- +<p>{{ SeeCompatTable() }}</p> +<p>Network Information API 將提供系統連線的相關資訊，如使用者裝置的現有頻寬，或目前的連線狀態。根據使用者的連線情形，可進一步選擇高解析度或低解析度的內容。此完整的 API 另包含 domxref("Connection") 介面，以及 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Navigator" title="The Navigator interface represents the state and the identiy of the user agent. It allows scripts to query it and to register themselves to carry on some activities."><code>Navigator</code></a> 介面的單一屬性 ─ <a href="https://developer.mozilla.org/en-US/docs/Web/API/Navigator.connection" title="The NetworkInformation.connection read-only property represents a Connection containing information about the system's connection, such as the current bandwidth of the user's device or whether the connection is metered. This could be used to select high d"><code>Navigator.connection</code></a>。</p> +<h2 id="偵測連線變化">偵測連線變化</h2> +<p>此範例將觀察使用者連線的變化。舉例來說，當使用者從高價位連線轉用低價位連線時，就會降低頻寬需求以避免連線費用暴增，並採用類似 Apps 受到警示的方法。</p> +<pre class="brush: js">var connection = navigator.connection || navigator.mozConnection || navigator.webkitConnection; + +function updateConnectionStatus() { + alert("Connection bandwidth: " + connection.bandwidth + " MB/s"); + if (connection.metered) { + alert("The connection is metered!"); + } +} + +connection.addEventListener("change", updateConnectionStatus); +updateConnectionStatus(); +</pre> +<h2 id="Specifications" name="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('Network Information', '', 'Network Information API') }}</td> + <td>{{ Spec2('Network Information') }}</td> + <td>Initial specification</td> + </tr> + </tbody> +</table> +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> +<p>{{Page('/en-US/docs/Web/API/window.navigator.connection','Browser compatibility')}}</p> +<h2 id="See_also">See also</h2> +<ul> + <li>{{ spec("http://dvcs.w3.org/hg/dap/raw-file/tip/network-api/Overview.html", "Network Information API Specification", "ED") }}</li> + <li><a href="/en/Online_and_offline_events" title="en/Online_and_offline_events">線上與離線事件</a></li> + <li>{{domxref("window.navigator.connection")}}</li> +</ul> diff --git a/files/zh-tw/web/api/node/childnodes/index.html b/files/zh-tw/web/api/node/childnodes/index.html new file mode 100644 index 0000000000..a828bd781b --- /dev/null +++ b/files/zh-tw/web/api/node/childnodes/index.html @@ -0,0 +1,66 @@ +--- +title: Node.childNodes +slug: Web/API/Node/childNodes +translation_of: Web/API/Node/childNodes +--- +<div> +<div>{{APIRef("DOM")}}</div> +</div> + +<p><code><strong>Node.childNodes</strong></code> 唯讀屬性會回傳一個<em>即時更新的動態集合（live collection）</em>，其包含了指定元素的子{{domxref("Node","節點")}}，而第一個子節點會被指派為索引 0。</p> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox">var <var>ndList</var> = elementNodeReference.childNodes; +</pre> + +<p><var>ndList</var> 是一個 {{domxref("NodeList")}}，為一個有順序性、由目前元素之 DOM 子節點組成之集合。假如目前元素沒有子節點，則 <var>ndList</var> 會是空的。</p> + +<p>範例</p> + +<pre class="brush:js">// parg is an object reference to a <p> element + +// First check that the element has child nodes +if (parg.hasChildNodes()) { + var children = parg.childNodes; + + for (var i = 0; i < children.length; i++) { + // do something with each child as children[i] + // NOTE: List is live, adding or removing children will change the list + } +}</pre> + +<hr> +<pre class="brush:js">// This is one way to remove all children from a node +// box is an object reference to an element + +while (box.firstChild) { + //The list is LIVE so it will re-index each call + box.removeChild(box.firstChild); +}</pre> + +<h2 id="Notes" name="Notes">備註</h2> + +<p>The items in the collection of nodes are objects and not strings. To get data from node objects, use their properties (e.g. <code>elementNodeReference.childNodes[1].nodeName</code> to get the name, etc.).</p> + +<p>The <code>document</code> object itself has 2 children: the Doctype declaration and the root element, typically referred to as <code>documentElement</code>. (In (X)HTML documents this is the <code>HTML</code> element.)</p> + +<p><code>childNodes</code> includes all child nodes, including non-element nodes like text and comment nodes. To get a collection of only elements, use {{ domxref("ParentNode.children") }} instead.</p> + +<h2 id="Specification" name="Specification">規範</h2> + +<ul> + <li><a class="external" href="http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/core.html#ID-1451460987">W3C DOM 2 Core: childNodes</a></li> + <li><a class="external" href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#ID-1451460987">W3C DOM 3 Core: childNodes</a></li> + <li><a class="external" href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#ID-536297177">W3C DOM 3 NodeList interface</a></li> +</ul> + +<h2 id="See_also" name="See_also">參見</h2> + +<ul> + <li>{{ domxref("Node.firstChild") }}</li> + <li>{{ domxref("Node.lastChild") }}</li> + <li>{{ domxref("Node.nextSibling") }}</li> + <li>{{ domxref("Node.previousSibling") }}</li> + <li>{{ domxref("ParentNode.children") }}</li> +</ul> diff --git a/files/zh-tw/web/api/node/clonenode/index.html b/files/zh-tw/web/api/node/clonenode/index.html new file mode 100644 index 0000000000..2bd1998650 --- /dev/null +++ b/files/zh-tw/web/api/node/clonenode/index.html @@ -0,0 +1,160 @@ +--- +title: Node.cloneNode() +slug: Web/API/Node/cloneNode +translation_of: Web/API/Node/cloneNode +--- +<div>{{APIRef("DOM")}}</div> + +<p><strong><code>Node.cloneNode()</code></strong> 方法會回傳一個呼叫此方法之節點物件的拷貝。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">var <em><var>dupNode</var></em> = <em><var>node</var></em>.cloneNode(<em><var>deep</var></em>); +</pre> + +<dl> + <dt><em>node</em></dt> + <dd>The node to be cloned.</dd> + <dt><em>dupNode</em></dt> + <dd>The new node that will be a clone of <code>node</code></dd> + <dt><em>deep {{optional_inline}}</em></dt> + <dd><code>true</code> if the children of the node should also be cloned, or <code>false</code> to clone only the specified node.</dd> +</dl> + +<div class="note"> +<p><strong>Note:</strong> In the DOM4 specification (as implemented in Gecko 13.0 {{geckoRelease(13)}}), <code>deep</code> is an optional argument. If omitted, the method acts as if the value of <code>deep</code> was <strong><code>true</code></strong>, defaulting to using deep cloning as the default behavior. To create a shallow clone, <code>deep</code> must be set to <code>false</code>.</p> + +<p>This behavior has been changed in the latest spec, and if omitted, the method will act as if the value of <code>deep</code> was <strong><code>false</code></strong>. Though It's still optional, you should always provide the <code>deep</code> argument both for backward and forward compatibility. With Gecko 28.0 {{geckoRelease(28)}}), the console warned developers not to omit the argument. Starting with Gecko 29.0 {{geckoRelease(29)}}), a shallow clone is defaulted instead of a deep clone.</p> +</div> + +<h2 id="範例">範例</h2> + +<pre class="brush: js">var p = document.getElementById("para1"); +var p_prime = p.cloneNode(true); +</pre> + +<h2 id="備註">備註</h2> + +<p id="not-event-listeners">Cloning a node copies all of its attributes and their values, including intrinsic (in–line) listeners. It does not copy event listeners added using <a href="/en-US/docs/DOM/element.addEventListener"><code>addEventListener()</code></a> or those assigned to element properties. (e.g. <code>node.onclick = fn</code>) Moreover, for a <canvas> element, the painted image is not copied.</p> + +<p>The duplicate node returned by <code>cloneNode()</code> is not part of the document until it is added to another node that is part of the document using {{domxref("Node.appendChild()")}} or a similar method. It also has no parent until it is appended to another node.</p> + +<p>If <code>deep</code> is set to <code>false</code>, child nodes are not cloned. Any text that the node contains is not cloned either, as it is contained in one or more child {{domxref("Text")}} nodes.</p> + +<p>If <code>deep</code> evaluates to <code>true</code>, the whole subtree (including text that may be in child {{domxref("Text")}} nodes) is copied too. For empty nodes (e.g. {{HTMLElement("img")}} and {{HTMLElement("input")}} elements) it doesn't matter whether <code>deep</code> is set to <code>true</code> or <code>false</code>.</p> + +<div class="warning"><strong>Warning:</strong> <code>cloneNode()</code> may lead to duplicate element IDs in a document.</div> + +<p>If the original node has an ID and the clone is to be placed in the same document, the ID of the clone should be modified to be unique. Name attributes may need to be modified also, depending on whether duplicate names are expected.</p> + +<p>To clone a node for appending to a different document, use {{domxref("Document.importNode()")}} instead.</p> + +<h2 id="規範">規範</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("DOM WHATWG", "#dom-node-clonenode", "Node.cloneNode()")}}</td> + <td>{{Spec2("DOM WHATWG")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("DOM3 Core", "core.html#ID-3A0ED0A4", "Node.cloneNode()")}}</td> + <td>{{Spec2("DOM3 Core")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("DOM2 Core", "core.html#ID-3A0ED0A4", "Node.cloneNode()")}}</td> + <td>{{Spec2("DOM2 Core")}}</td> + <td>Initial definition</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>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>deep</code> as an optional parameter</td> + <td> + <p>{{CompatVersionUnknown}}<sup>[1]</sup></p> + </td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoDesktop("13.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td> + <p>{{CompatVersionUnknown}}<sup>[1]</sup></p> + </td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>deep</code> as an optional parameter</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("13.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Default value for the <code>deep</code> parameter is <code>false</code>.</p> diff --git a/files/zh-tw/web/api/node/index.html b/files/zh-tw/web/api/node/index.html new file mode 100644 index 0000000000..fc04145fce --- /dev/null +++ b/files/zh-tw/web/api/node/index.html @@ -0,0 +1,529 @@ +--- +title: Node +slug: Web/API/Node +tags: + - API + - DOM + - DOM Reference + - Interface + - NeedsTranslation + - Node + - Reference + - TopicStub +translation_of: Web/API/Node +--- +<div>{{APIRef("DOM")}}</div> + +<p><strong><code>Node</code></strong> 是一個被多種 DOM 類型繼承的介面，它讓各種類型的 DOM 都能以同樣的方式來操作。如繼承了相同的方法，或能以相同的方式測試。</p> + +<p><code>Node</code> 繼承自 {{domxref("EventTarget")}}，而繼承了 <code>Node</code> 的屬性及方法的介面則有：{{domxref("Document")}}、{{domxref("Element")}}、{{domxref("CharacterData")}}（被 {{domxref("Text")}}、{{domxref("Comment")}} 以及 {{domxref("CDATASection")}} 所繼承）、{{domxref("ProcessingInstruction")}}、{{domxref("DocumentFragment")}}、{{domxref("DocumentType")}}、{{domxref("Notation")}}、{{domxref("Entity")}}、{{domxref("EntityReference")}}。</p> + +<p>These interfaces may return null in particular cases where the methods and properties are not relevant. They may throw an exception - for example when adding children to a node type for which no children can exist.</p> + +<p>{{InheritanceDiagram}}</p> + +<h2 id="屬性">屬性</h2> + +<p><em>Inherits properties from its parents {{domxref("EventTarget")}}</em>.<sup>[1]</sup></p> + +<dl> + <dt>{{domxref("Node.baseURI")}} {{readonlyInline}}</dt> + <dd>Returns a {{domxref("DOMString")}} representing the base URL. The concept of base URL changes from one language to another; in HTML, it corresponds to the protocol, the domain name and the directory structure, that is all until the last <code>'/'</code>.</dd> + <dt>{{domxref("Node.baseURIObject")}} {{Non-standard_inline()}} {{ Fx_minversion_inline("3") }}</dt> + <dd>(Not available to web content.) The read-only {{ Interface("nsIURI") }} object representing the base URI for the element.</dd> + <dt>{{domxref("Node.childNodes")}} {{readonlyInline}}</dt> + <dd>Returns a live {{domxref("NodeList")}} containing all the children of this node. {{domxref("NodeList")}} being live means that if the children of the <code>Node</code> change, the {{domxref("NodeList")}} object is automatically updated.</dd> + <dt>{{domxref("Node.firstChild")}} {{readonlyInline}}</dt> + <dd>Returns a {{domxref("Node")}} representing the first direct child node of the node, or <code>null</code> if the node has no child.</dd> + <dt>{{domxref("Node.lastChild")}} {{readonlyInline}}</dt> + <dd>Returns a {{domxref("Node")}} representing the last direct child node of the node, or <code>null</code> if the node has no child.</dd> + <dt>{{domxref("Node.nextSibling")}} {{readonlyInline}}</dt> + <dd>Returns a {{domxref("Node")}} representing the next node in the tree, or <code>null</code> if there isn't such node.</dd> + <dt>{{domxref("Node.nodeName")}} {{readonlyInline}}</dt> + <dd>Returns a {{domxref("DOMString")}} containing the name of the <code>Node</code>. The structure of the name will differ with the node type. E.g. An {{domxref("HTMLElement")}} will contain the name of the corresponding tag, like <code>'audio'</code> for an {{domxref("HTMLAudioElement")}}, a {{domxref("Text")}} node will have the <code>'#text'</code> string, or a {{domxref("Document")}} node will have the <code>'#document'</code> string.</dd> + <dt>{{domxref("Node.nodePrincipal")}} {{Non-standard_inline()}}{{ Fx_minversion_inline("3") }}</dt> + <dd>A {{ Interface("nsIPrincipal") }} representing the node principal.</dd> + <dt>{{domxref("Node.nodeType")}}{{readonlyInline}}</dt> + <dd>Returns an <code>unsigned short</code> representing the type of the node. Possible values are: + <table class="standard-table"> + <tbody> + <tr> + <th scope="col">Name</th> + <th scope="col">Value</th> + </tr> + <tr> + <td><code>ELEMENT_NODE</code></td> + <td><code>1</code></td> + </tr> + <tr> + <td><code>ATTRIBUTE_NODE</code> {{deprecated_inline()}}</td> + <td><code>2</code></td> + </tr> + <tr> + <td><code>TEXT_NODE</code></td> + <td><code>3</code></td> + </tr> + <tr> + <td><code>CDATA_SECTION_NODE</code> {{deprecated_inline()}}</td> + <td><code>4</code></td> + </tr> + <tr> + <td><code>ENTITY_REFERENCE_NODE</code> {{deprecated_inline()}}</td> + <td><code>5</code></td> + </tr> + <tr> + <td><code>ENTITY_NODE</code> {{deprecated_inline()}}</td> + <td><code>6</code></td> + </tr> + <tr> + <td><code>PROCESSING_INSTRUCTION_NODE</code></td> + <td><code>7</code></td> + </tr> + <tr> + <td><code>COMMENT_NODE</code></td> + <td><code>8</code></td> + </tr> + <tr> + <td><code>DOCUMENT_NODE</code></td> + <td><code>9</code></td> + </tr> + <tr> + <td><code>DOCUMENT_TYPE_NODE</code></td> + <td><code>10</code></td> + </tr> + <tr> + <td><code>DOCUMENT_FRAGMENT_NODE</code></td> + <td><code>11</code></td> + </tr> + <tr> + <td><code>NOTATION_NODE</code> {{deprecated_inline()}}</td> + <td><code>12</code></td> + </tr> + </tbody> + </table> + </dd> + <dt>{{domxref("Node.nodeValue")}}</dt> + <dd>Returns / Sets the value of the current node</dd> + <dt>{{domxref("Node.ownerDocument")}} {{readonlyInline}}</dt> + <dd>Returns the {{domxref("Document")}} that this node belongs to. If no document is associated with it, returns <code>null</code>.</dd> + <dt>{{domxref("Node.parentNode")}} {{readonlyInline}}</dt> + <dd>Returns a {{domxref("Node")}} that is the parent of this node. If there is no such node, like if this node is the top of the tree or if doesn't participate in a tree, this property returns <code>null</code>.</dd> + <dt>{{domxref("Node.parentElement")}} {{readonlyInline}}</dt> + <dd>Returns an {{domxref("Element")}} that is the parent of this node. If the node has no parent, or if that parent is not an {{domxref("Element")}}, this property returns <code>null</code>.</dd> + <dt>{{domxref("Node.previousSibling")}} {{readonlyInline}}</dt> + <dd>Returns a {{domxref("Node")}} representing the previous node in the tree, or <code>null</code> if there isn't such node.</dd> + <dt>{{domxref("Node.textContent")}}</dt> + <dd>Returns / Sets the textual content of an element and all its descendants.</dd> +</dl> + +<h3 id="Deprecated_properties">Deprecated properties</h3> + +<dl> + <dt>{{domxref("Node.rootNode")}} {{readOnlyInline}} {{deprecated_inline}}</dt> + <dd>Returns a {{domxref("Node")}} object representing the topmost node in the tree, or the current node if it's the topmost node in the tree. This has been replaced by {{domxref("Node.getRootNode()")}}.</dd> +</dl> + +<h3 id="Obsolete_properties">Obsolete properties</h3> + +<dl> + <dt>{{domxref("Node.localName")}} {{obsolete_inline}}{{readonlyInline}}</dt> + <dd>Returns a {{domxref("DOMString")}} representing the local part of the qualified name of an element. + <div class="note"> + <p><strong>Note:</strong> In Firefox 3.5 and earlier, the property upper-cases the local name for HTML elements (but not XHTML elements). In later versions, this does not happen, so the property is in lower case for both HTML and XHTML. {{gecko_minversion_inline("1.9.2")}}</p> + </div> + </dd> + <dt>{{domxref("Node.namespaceURI")}} {{obsolete_inline}}{{readonlyInline}}</dt> + <dd>The namespace URI of this node, or <code>null</code> if it is no namespace. + <div class="note"> + <p><strong>Note:</strong> In Firefox 3.5 and earlier, HTML elements are in no namespace. In later versions, HTML elements are in the <code><a class="linkification-ext external" href="https://www.w3.org/1999/xhtml/" title="Linkification: http://www.w3.org/1999/xhtml">https://www.w3.org/1999/xhtml/</a></code> namespace in both HTML and XML trees. {{gecko_minversion_inline("1.9.2")}}</p> + </div> + </dd> + <dt>{{domxref("Node.prefix")}} {{obsolete_inline}}{{readonlyInline}}</dt> + <dd>Is a {{domxref("DOMString")}} representing the namespace prefix of the node, or <code>null</code> if no prefix is specified.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>Inherits methods from its parent, {{domxref("EventTarget")}}</em>.<sup>[1]</sup></p> + +<dl> + <dt>{{domxref("Node.appendChild()")}}</dt> + <dd>Adds the specified childNode argument as the last child to the current node.<br> + If the argument referenced an existing node on the DOM tree, the node will be detached from its current position and attached at the new position.</dd> + <dt>{{domxref("Node.cloneNode()")}}</dt> + <dd>Clone a {{domxref("Node")}}, and optionally, all of its contents. By default, it clones the content of the node.</dd> + <dt>{{domxref("Node.compareDocumentPosition()")}}</dt> + <dd>Compares the position of the current node against another node in any other document.</dd> + <dt>{{domxref("Node.contains()")}}</dt> + <dd>Returns a {{jsxref("Boolean")}} value indicating whether a node is a descendant of a given node or not.</dd> + <dt>{{domxref("Node.getRootNode()")}}</dt> + <dd>Returns the context object's root which optionally includes the shadow root if it is available.</dd> + <dt>{{domxref("Node.hasChildNodes()")}}</dt> + <dd>Returns a {{jsxref("Boolean")}} indicating if the element has any child nodes, or not.</dd> + <dt>{{domxref("Node.insertBefore()")}}</dt> + <dd>Inserts a {{domxref("Node")}} before the reference node as a child of the current node.</dd> + <dt>{{domxref("Node.isDefaultNamespace()")}}</dt> + <dd>Accepts a namespace URI as an argument and returns a {{jsxref("Boolean")}} with a value of <code>true</code> if the namespace is the default namespace on the given node or <code>false</code> if not.</dd> + <dt>{{domxref("Node.isEqualNode()")}}</dt> + <dd>Returns a {{jsxref("Boolean")}} which indicates whether or not two nodes are of the same type and all their defining data points match.</dd> + <dt>{{domxref("Node.isSameNode()")}}</dt> + <dd>Returns a {{jsxref("Boolean")}} value indicating whether or not the two nodes are the same (that is, they reference the same object).</dd> + <dt>{{domxref("Node.lookupPrefix()")}}</dt> + <dd>Returns a {{domxref("DOMString")}} containing the prefix for a given namespace URI, if present, and <code>null</code> if not. When multiple prefixes are possible, the result is implementation-dependent.</dd> + <dt>{{domxref("Node.lookupNamespaceURI()")}}</dt> + <dd>Accepts a prefix and returns the namespace URI associated with it on the given node if found (and <code>null</code> if not). Supplying <code>null</code> for the prefix will return the default namespace.</dd> + <dt>{{domxref("Node.normalize()")}}</dt> + <dd>Clean up all the text nodes under this element (merge adjacent, remove empty).</dd> + <dt>{{domxref("Node.removeChild()")}}</dt> + <dd>Removes a child node from the current element, which must be a child of the current node.</dd> + <dt>{{domxref("Node.replaceChild()")}}</dt> + <dd>Replaces one child {{domxref("Node")}} of the current one with the second one given in parameter.</dd> +</dl> + +<h3 id="Obsolete_methods">Obsolete methods</h3> + +<dl> + <dt>{{domxref("Node.getFeature()")}} {{obsolete_inline}}</dt> + <dd>x</dd> + <dt>{{domxref("Node.getUserData()")}} {{obsolete_inline}}</dt> + <dd>Allows a user to get some {{domxref("DOMUserData")}} from the node.</dd> + <dt>{{domxref("Node.hasAttributes()")}} {{obsolete_inline}}</dt> + <dd>Returns a {{jsxref("Boolean")}} indicating if the element has any attributes, or not.</dd> + <dt>{{domxref("Node.isSupported()")}} {{obsolete_inline}}</dt> + <dd>Returns a {{jsxref("Boolean")}} flag containing the result of a test whether the DOM implementation implements a specific feature and this feature is supported by the specific node.</dd> + <dt>{{domxref("Node.setUserData()")}} {{obsolete_inline}}</dt> + <dd>Allows a user to attach, or remove, {{domxref("DOMUserData")}} to the node.</dd> +</dl> + +<h2 id="範例">範例</h2> + +<h3 id="Browse_all_child_nodes">Browse all child nodes</h3> + +<p>The following function recursively cycles all child nodes of a node and executes a callback function upon them (and upon the parent node itself).</p> + +<pre class="brush: js">function DOMComb (oParent, oCallback) { + if (oParent.hasChildNodes()) { + for (var oNode = oParent.firstChild; oNode; oNode = oNode.nextSibling) { + DOMComb(oNode, oCallback); + } + } + oCallback.call(oParent); +}</pre> + +<h4 id="Syntax">Syntax</h4> + +<pre class="syntaxbox">DOMComb(parentNode, callbackFunction);</pre> + +<h4 id="Description">Description</h4> + +<p>Recursively cycle all child nodes of <code>parentNode</code> and <code>parentNode</code> itself and execute the <code>callbackFunction</code> upon them as <a href="/en-US/docs/JavaScript/Reference/Operators/this" title="en-US/docs/JavaScript/Reference/Operators/this"><code>this</code></a> objects.</p> + +<h4 id="Parameters">Parameters</h4> + +<dl> + <dt><code>parentNode</code></dt> + <dd>The parent node (<code><strong>Node</strong> <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Object" title="en-US/docs/JavaScript/Reference/Global_Objects/Object">Object</a></code>).</dd> + <dt><code>callbackFunction</code></dt> + <dd>The callback function (<a href="/en-US/docs/JavaScript/Reference/Global_Objects/Function" title="en-US/docs/JavaScript/Reference/Global_Objects/Function"><code>Function</code></a>).</dd> +</dl> + +<h4 id="Sample_usage">Sample usage</h4> + +<p>The following example send to the <code>console.log</code> the text content of the body:</p> + +<pre class="brush: js">function printContent () { + if (this.nodeValue) { console.log(this.nodeValue); } +} + +onload = function () { + DOMComb(document.body, printContent); +};</pre> + +<h3 id="Remove_all_children_nested_within_a_node">Remove all children nested within a node</h3> + +<pre class="brush: js">Element.prototype.removeAll = function () { + while (this.firstChild) { this.removeChild(this.firstChild); } + return this; +};</pre> + +<h4 id="Sample_usage_2">Sample usage</h4> + +<pre class="brush: js">/* ... an alternative to document.body.innerHTML = "" ... */ +document.body.removeAll();</pre> + +<h2 id="規範">規範</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('DOM WHATWG', '#interface-node', 'Node')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>Removed the following properties: <code>attributes</code>, <code>namespaceURI</code>, <code>prefix</code>, and <code>localName</code>.<br> + Removed the following methods: <code>isSupported()</code>, <code>hasAttributes()</code>, <code>getFeature()</code>, <code>setUserData()</code>, and <code>getUserData()</code>.</td> + </tr> + <tr> + <td>{{SpecName('DOM3 Core', 'core.html#ID-1950641247', 'Node')}}</td> + <td>{{Spec2('DOM3 Core')}}</td> + <td>The methods <code>insertBefore()</code>, <code>replaceChild()</code>, <code>removeChild()</code>, and <code>appendChild()</code> returns one more kind of error (<code>NOT_SUPPORTED_ERR</code>) if called on a {{domxref("Document")}}.<br> + The <code>normalize()</code> method has been modified so that {{domxref("Text")}} node can also be normalized if the proper {{domxref("DOMConfiguration")}} flag is set.<br> + Added the following methods: <code>compareDocumentPosition()</code>, <code>isSameNode()</code>, <code>lookupPrefix()</code>, <code>isDefaultNamespace()</code>, <code>lookupNamespaceURI()</code>, <code>isEqualNode()</code>, <code>getFeature()</code>, <code>setUserData()</code>, and <code>getUserData().</code><br> + Added the following properties: <code>baseURI</code> and <code>textContent</code>.</td> + </tr> + <tr> + <td>{{SpecName('DOM2 Core', 'core.html#ID-1950641247', 'Node')}}</td> + <td>{{Spec2('DOM2 Core')}}</td> + <td>The <code>ownerDocument</code> property was slightly modified so that {{domxref("DocumentFragment")}} also returns <code>null</code>.<br> + Added the following properties: <code>namespaceURI</code>, <code>prefix</code>, and <code>localName</code>.<br> + Added the following methods: <code>normalize()</code>, <code>isSupported()</code> and <code>hasAttributes()</code>.</td> + </tr> + <tr> + <td>{{SpecName('DOM1', 'level-one-core.html#ID-1950641247', 'Node')}}</td> + <td>{{Spec2('DOM1')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>{{CompatVersionUnknown}}<sup>[1]</sup></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}<sup>[1]</sup></td> + <td>{{CompatVersionUnknown}}<sup>[1]</sup></td> + </tr> + <tr> + <td><code>getFeature()</code>{{obsolete_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoDesktop("1.0")}}<br> + {{CompatNo}}{{CompatGeckoDesktop("7.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>getUserData()</code>, <code>setUserData()</code> and <code>hasAttributes()</code> {{deprecated_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoDesktop("1.0")}}<br> + {{CompatNo}}{{CompatGeckoDesktop("22.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>isSameNode()</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoDesktop("1.0")}}<br> + Removed in {{CompatGeckoDesktop("10")}}<br> + Returned in {{CompatGeckoDesktop("48")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>isSupported()</code> {{obsolete_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoDesktop("1.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>attributes</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoDesktop("1.0")}}<br> + {{CompatNo}}{{CompatGeckoDesktop("22.0")}}<sup>[2]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>rootNode()</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>CompatGeckoDesktop(48)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>namespaceURI</code>, <code>localName</code>, <code>prefix</code> {{obsolete_inline}}</td> + <td>{{CompatVersionUnknown}}<br> + {{CompatNo}}46.0<sup>[3]</sup></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}<br> + {{CompatNo}}48.0<sup>[3]</sup></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>getRootNode()</code>, and <code>rootNode</code> deprecated</td> + <td>{{CompatChrome(54.0)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoDesktop(53)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatOpera(41)}}</td> + <td>{{CompatUnknown}}</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>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + <th>Chrome for Android</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}<sup>[1]</sup></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("1.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}<sup>[1]</sup></td> + <td>{{CompatVersionUnknown}}<sup>[1]</sup></td> + <td>{{CompatVersionUnknown}}<sup>[1]</sup></td> + </tr> + <tr> + <td><code>getFeature()</code>{{obsolete_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("1.0")}}<br> + {{CompatNo}}{{CompatGeckoDesktop("7.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>getUserData()</code>, <code>setUserData()</code> and <code>hasAttributes()</code> {{deprecated_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>isSameNode()</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td> + <p>{{CompatGeckoDesktop("1.0")}}<br> + Removed in {{CompatGeckoDesktop("10")}}<br> + Returned in {{CompatGeckoDesktop("48")}}</p> + </td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>isSupported()</code> {{obsolete_inline}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>attributes</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>rootNode()</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile(48)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>namespaceURI</code>, <code>localName</code>, <code>prefix</code> {{obsolete_inline}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}<br> + {{CompatNo}}48.0[3]</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>getRootNode()</code>, and <code>rootNode</code> deprecated</td> + <td>{{CompatNo}}</td> + <td>{{CompatChrome(54.0)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile(53)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatOperaMobile(41)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatChrome(54.0)}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] WebKit and old versions of Blink incorrectly do not make <code>Node</code> inherit from {{domxref("EventTarget")}}.</p> + +<p>[2] In Gecko 22.0 {{geckoRelease("22.0")}} the <code>attributes</code> property was moved to {{domxref("Element")}}.</p> + +<p>[3] The properties were moved to the {{domxref("Element")}} and {{domxref("Attr")}} APIs according to the DOM4 standard.</p> diff --git a/files/zh-tw/web/api/node/innertext/index.html b/files/zh-tw/web/api/node/innertext/index.html new file mode 100644 index 0000000000..4c8a4272fc --- /dev/null +++ b/files/zh-tw/web/api/node/innertext/index.html @@ -0,0 +1,86 @@ +--- +title: Node.innerText +slug: Web/API/Node/innerText +translation_of: Web/API/HTMLElement/innerText +--- +<div>{{APIRef("DOM")}}</div> + +<h2 id="概述">概述</h2> + +<p><code><strong>Node.innerText</strong></code> 是一個代表節點及其後代之「已渲染」（rendered）文字內容的屬性。如同一個存取器，<code>Node.innerText</code> 近似於使用者利用游標選取成高亮後複製至剪貼簿之元素的內容。此功能最初由 Internet Explorer 提供，並在被所有主要瀏覽器採納之後，於 2016 年正式成為 HTML 標準。</p> + +<p>{{domxref("Node.textContent")}} 屬性是一個相似的選擇，但兩者之間仍有非常不同的差異。</p> + +<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('HTML WHATWG', 'dom.html#the-innertext-idl-attribute', 'innerText')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>Introduced, based on the <a href="https://github.com/rocallahan/innerText-spec">draft of the innerText specification</a>. See <a href="https://github.com/whatwg/html/issues/465">whatwg/html#465</a> and <a href="https://github.com/whatwg/compat/issues/5">whatwg/compat#5</a> for history.</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_Compatibility" name="Browser_Compatibility">瀏覽器相容性</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>4</td> + <td>{{ CompatGeckoDesktop(45) }}</td> + <td>6</td> + <td>9.6 (probably earlier)</td> + <td>3</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>2.3 (probably earlier)</td> + <td>{{ CompatGeckoMobile(45) }}</td> + <td>10 (probably earlier)</td> + <td>12</td> + <td>4.1 (probably earlier)</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("HTMLElement.outerText")}}</li> + <li>{{domxref("Element.innerHTML")}}</li> +</ul> diff --git a/files/zh-tw/web/api/node/insertbefore/index.html b/files/zh-tw/web/api/node/insertbefore/index.html new file mode 100644 index 0000000000..393cc88d80 --- /dev/null +++ b/files/zh-tw/web/api/node/insertbefore/index.html @@ -0,0 +1,167 @@ +--- +title: Node.insertBefore() +slug: Web/API/Node/insertBefore +translation_of: Web/API/Node/insertBefore +--- +<div> +<div>{{APIRef("DOM")}}</div> +</div> + +<p><code><strong>Node.insertBefore()</strong></code> 方法將一個節點安插在參考節點之前，作為某個特定父節點之子節點。If the given child is a reference to an existing node in the document, <code>insertBefore()</code> moves it from its current position to the new position (there is no requirement to remove the node from its parent node before appending it to some other node).</p> + +<p>同一個節點並不會同時出現在兩個地方。所以當節點已經有父節點，它會先被移除，然後被插入在新的位置上。The {{domxref("Node.cloneNode()")}} can be used to make a copy of the node before appending it under the new parent. Note that the copies made with <code>cloneNode</code> will not be automatically kept in sync.</p> + +<p>若參考節點為 <code>null</code>, 那需插入的節點就會成為特定父節點的最後一個子節點。</p> + +<p>If the given child is a {{domxref("DocumentFragment")}}, the entire contents of the {{domxref("DocumentFragment")}} are moved into the child list of the specified parent node.</p> + +<h2 id="Syntax" name="Syntax">Syntax</h2> + +<pre class="syntaxbox">var <em>insertedNode</em> = <em>parentNode</em>.insertBefore(<em>newNode</em>, <em>referenceNode</em>); +</pre> + +<p>If <code><var>referenceNode</var></code> is <code>null</code>, the <code><var>newNode</var></code> is inserted at the end of the list of child nodes.</p> + +<div class="note"> +<p><em><code>referenceNode</code></em> <strong>並非</strong>可選擇的參數 -- 一定要傳入一個<code>節點</code>或是 <code>null</code>。若是傳入失敗或不正確的參數，可能會依不同的瀏覽器版本而有<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=119489">不同的</a><a href="https://code.google.com/p/chromium/issues/detail?id=419780">行為</a>。</p> +</div> + +<h2 id="Returns" name="Returns">Returns</h2> + +<p>會回傳新加入的子節點。若該值(<code>newNode</code>)是{{domxref("DocumentFragment")}}, 則回傳空的 {{domxref("DocumentFragment")}}。</p> + +<h2 id="Example_2">Example</h2> + +<pre class="brush: html"><div id="parentElement"> + <span id="childElement">foo bar</span> +</div> + +<script> +// Create the new node to insert +var newNode = document.createElement("span"); + +// Get a reference to the parent node +var parentDiv = document.getElementById("childElement").parentNode; + +// Begin test case [ 1 ] : Exist a childElement --> All working correctly +var sp2 = document.getElementById("childElement"); +parentDiv.insertBefore(newNode, sp2); +// End test case [ 1 ] + +// Begin test case [ 2 ] : childElement is of Type undefined +var sp2 = undefined; // Not exist a node of id "childElement" +parentDiv.insertBefore(newNode, sp2); // Implicit dynamic cast to type Node +// End test case [ 2 ] + +// Begin test case [ 3 ] : childElement is of Type "undefined" ( string ) +var sp2 = "undefined"; // Not exist a node of id "childElement" +parentDiv.insertBefore(newNode, sp2); // Generate "Type Error: Invalid Argument" +// End test case [ 3 ] +</script></pre> + +<ul> + <li><code>insertedNode</code> 被插入的節點，也就是 <code>newNode</code>。</li> + <li><code>parentNode</code> 指定的父節點。</li> + <li><code>newNode</code> 被插入的節點。</li> + <li><code>referenceNode</code> 參考節點。The node before which <code>newNode</code> is inserted.</li> +</ul> + +<h2 id="Example" name="Example">Example</h2> + +<pre class="brush:html"><div id="parentElement"> + <span id="childElement">foo bar</span> +</div> + +<script> +// Create a new, plain <span> element +var sp1 = document.createElement("span"); + +// Get a reference to the element, before we want to insert the element +var sp2 = document.getElementById("childElement"); +// Get a reference to the parent element +var parentDiv = sp2.parentNode; + +// Insert the new element into the DOM before sp2 +parentDiv.insertBefore(sp1, sp2); +</script> +</pre> + +<p>There is no <code>insertAfter</code> method. It can be emulated by combining the <code>insertBefore</code> method with <code><a href="/en-US/docs/DOM/Node.nextSibling" title="DOM/Node.nextSibling">nextSibling</a></code>.</p> + +<p>In the previous example, <code>sp1</code> could be inserted after <code>sp2</code> using:</p> + +<pre><code>parentDiv.insertBefore(sp1, sp2.nextSibling);</code></pre> + +<p>If <code>sp2</code> does not have a next sibling, then it must be the last child — <code>sp2.nextSibling</code> returns <code>null</code>, and <code>sp1</code> is inserted at the end of the child node list (immediately after <code>sp2</code>).</p> + +<h2 id="Example" name="Example">Example</h2> + +<p>Insert an element before the first child element, using the <a href="/en-US/docs/DOM/Node.firstChild" title="Node.firstChild">firstChild</a> property.</p> + +<pre class="brush:js">// Get a reference to the element in which we want to insert a new node +var parentElement = document.getElementById('parentElement'); +// Get a reference to the first child +var theFirstChild = parentElement.firstChild; + +// Create a new element +var newElement = document.createElement("div"); + +// Insert the new element before the first child +parentElement.insertBefore(newElement, theFirstChild); +</pre> + +<p>When the element does not have a first child, then <code>firstChild</code> is <code>null</code>. The element is still appended to the parent, after the last child. Since the parent element did not have a first child, it did not have a last child either. Consequently, the new element is the only element, after insertion.</p> + +<h2 id="Browser_Compatibility" name="Browser_Compatibility">Browser compatibility</h2> + + + +<p>{{Compat("api.Node.insertBefore")}}</p> + +<h2 id="Specifications" name="Specifications">Specifications</h2> + +<table class="spectable standard-table"> + <tbody> + <tr> + <th scope="col">Specification</th> + <th scope="col">Status</th> + <th scope="col">Comment</th> + </tr> + <tr> + <td>{{SpecName('DOM WHATWG','#dom-node-insertbefore','Node.insertBefore')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>Fixes errors in the insertion algorithm</td> + </tr> + <tr> + <td>{{SpecName('DOM4','#dom-node-insertbefore','Node.insertBefore')}}</td> + <td>{{Spec2('DOM4')}}</td> + <td>Describes the algorithm in more detail</td> + </tr> + <tr> + <td>{{SpecName('DOM3 Core','core.html#ID-952280727','Node.insertBefore')}}</td> + <td>{{Spec2('DOM3 Core')}}</td> + <td>No notable changes</td> + </tr> + <tr> + <td>{{SpecName('DOM2 Core','core.html#ID-952280727','Node.insertBefore')}}</td> + <td>{{Spec2('DOM2 Core')}}</td> + <td>No notable changes</td> + </tr> + <tr> + <td>{{SpecName('DOM1','level-one-core.html#method-insertBefore','Node.insertBefore')}}</td> + <td>{{Spec2('DOM1')}}</td> + <td>Introduced</td> + </tr> + </tbody> +</table> + +<h2 id="See_also" name="See_also">See also</h2> + +<ul> + <li>{{domxref("Node.removeChild()")}}</li> + <li>{{domxref("Node.replaceChild()")}}</li> + <li>{{domxref("Node.appendChild()")}}</li> + <li>{{domxref("Node.hasChildNodes()")}}</li> + <li>{{domxref("Element.insertAdjacentElement()")}}</li> + <li>{{domxref("ParentNode.prepend()")}}</li> +</ul> diff --git a/files/zh-tw/web/api/node/nodename/index.html b/files/zh-tw/web/api/node/nodename/index.html new file mode 100644 index 0000000000..b9c95b6e2f --- /dev/null +++ b/files/zh-tw/web/api/node/nodename/index.html @@ -0,0 +1,102 @@ +--- +title: Node.nodeName +slug: Web/API/Node/nodeName +translation_of: Web/API/Node/nodeName +--- +<div> +<div>{{APIRef("DOM")}}</div> +</div> + +<p><code><strong>Node.nodeName</strong></code> 唯讀屬性會回傳目前節點名稱的字串。</p> + +<p>不同類型節點之回傳值：</p> + +<table class="standard-table"> + <tbody> + <tr> + <th>介面</th> + <th>nodeName 值</th> + </tr> + <tr> + <td>{{domxref("Attr")}}</td> + <td>The value of {{domxref("Attr.name")}}</td> + </tr> + <tr> + <td>{{domxref("CDATASection")}}</td> + <td><code>"#cdata-section"</code></td> + </tr> + <tr> + <td>{{domxref("Comment")}}</td> + <td><code>"#comment"</code></td> + </tr> + <tr> + <td>{{domxref("Document")}}</td> + <td><code>"#document"</code></td> + </tr> + <tr> + <td>{{domxref("DocumentFragment")}}</td> + <td><code>"#document-fragment"</code></td> + </tr> + <tr> + <td>{{domxref("DocumentType")}}</td> + <td>The value of {{domxref("DocumentType.name")}}</td> + </tr> + <tr> + <td>{{domxref("Element")}}</td> + <td>The value of {{domxref("Element.tagName")}}</td> + </tr> + <tr> + <td>{{domxref("Entity")}}</td> + <td>The entity name</td> + </tr> + <tr> + <td>{{domxref("EntityReference")}}</td> + <td>The name of entity reference</td> + </tr> + <tr> + <td>{{domxref("Notation")}}</td> + <td>The notation name</td> + </tr> + <tr> + <td>{{domxref("ProcessingInstruction")}}</td> + <td>The value of {{domxref("ProcessingInstruction.target")}}</td> + </tr> + <tr> + <td>{{domxref("Text")}}</td> + <td><code>"#text"</code></td> + </tr> + </tbody> +</table> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">var <em>str</em> = <em>node</em>.nodeName; +</pre> + +<h2 id="範例">範例</h2> + +<p>Given the following markup:</p> + +<pre class="brush:html"><div id="d1">hello world</div> +<input type="text" id="t"/> +</pre> + +<p>and the following script:</p> + +<pre class="brush:js">var div1 = document.getElementById("d1"); +var text_field = document.getElementById("t"); + +text_field.value = div1.nodeName; +</pre> + +<p>In XHTML (or any other XML format), <code>text_field</code>'s value would read "div". However, in HTML, <code>text_field</code>'s value would read "DIV", because <code>nodeName</code> and <code>tagName</code> return in upper case on HTML elements in DOMs flagged as HTML documents. Read more <a href="http://ejohn.org/blog/nodename-case-sensitivity/" title="http://ejohn.org/blog/nodename-case-sensitivity/">details on nodeName case sensitivity in different browsers</a>.</p> + +<p>Note that <code><a href="/en-US/docs/DOM/element.tagName" title="DOM/element.tagName">tagName</a></code> property could have been used instead, since <code>nodeName</code> has the same value as <code>tagName</code> for an element. Bear in mind, however, that <code>nodeName</code> will return <code>#text</code> for text nodes while <code>tagName</code> will return <code>undefined</code>.</p> + +<h2 id="規範">規範</h2> + +<ul> + <li><a href="http://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-F68D095">DOM Level 2 Core: Node.nodeName</a></li> + <li><a href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#ID-F68D095">DOM Level 3 Core: Node.nodeName</a></li> + <li><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#apis-in-html-documents">HTML 5: APIs in HTML documents</a></li> +</ul> diff --git a/files/zh-tw/web/api/node/nodetype/index.html b/files/zh-tw/web/api/node/nodetype/index.html new file mode 100644 index 0000000000..606cbd1b94 --- /dev/null +++ b/files/zh-tw/web/api/node/nodetype/index.html @@ -0,0 +1,171 @@ +--- +title: Node.nodeType +slug: Web/API/Node/nodeType +translation_of: Web/API/Node/nodeType +--- +<div> +<div>{{APIRef("DOM")}}</div> +</div> + +<p><code><strong>Node.nodeType</strong></code> 唯讀屬性表示了節點物件的類型。</p> + +<h2 id="描述">描述</h2> + +<p>The <strong><code>nodeType</code></strong> property can be used to distinguish different kind of nodes, such that {{domxref("Element", "elements")}}, {{domxref("Text", "text")}} and {{domxref("Comment", "comments")}}, from each other.</p> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox"><em>var <var>type</var></em> = <var>node</var>.nodeType; +</pre> + +<p>Returns an integer value which specifies the type of the node; possible values are listed in {{anch("Node type constants")}}.</p> + +<h2 id="常數">常數</h2> + +<h3 id="節點類型常數">節點類型常數</h3> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Constant</th> + <th scope="col">Value</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{domxref("Node.ELEMENT_NODE")}} {{readonlyinline}}</td> + <td><code>1</code></td> + <td>表示元素的 {{domxref("Element")}} 節點，如 {{HTMLElement("body")}}、{{HTMLElement("a")}}、{{HTMLElement("p")}}、{{HTMLElement("script")}}、{{HTMLElement("style")}}、{{HTMLElement("html")}}、{{HTMLElement("h1")}} 或 {{HTMLElement("div")}}<font face="Consolas, Liberation Mono, Courier, monospace">。</font></td> + </tr> + <tr> + <td>{{domxref("Node.TEXT_NODE")}} {{readonlyinline}}</td> + <td><code>3</code></td> + <td>於表示元素的 {{domxref("Element")}} 節點或表示 {{Glossary("attribute", "HTML 元素屬性")}}的 {{domxref("Attr")}} 節點中，表示了實際文字字元的 {{domxref("Text")}} 節點，它包括了換行與空格。</td> + </tr> + <tr> + <td>{{domxref("Node.PROCESSING_INSTRUCTION_NODE")}} {{readonlyinline}}</td> + <td><code>7</code></td> + <td>A {{domxref("ProcessingInstruction")}} of an XML document such as <code><?xml-stylesheet ... ?></code> declaration.</td> + </tr> + <tr> + <td>{{domxref("Node.COMMENT_NODE")}} {{readonlyinline}}</td> + <td><code>8</code></td> + <td>表示註解的 {{domxref("Comment")}} 節點。</td> + </tr> + <tr> + <td>{{domxref("Node.DOCUMENT_NODE")}} {{readonlyinline}}</td> + <td><code>9</code></td> + <td>表示文件的 {{domxref("Document")}} 節點。</td> + </tr> + <tr> + <td>{{domxref("Node.DOCUMENT_TYPE_NODE")}} {{readonlyinline}}</td> + <td><code>10</code></td> + <td>表示文件類型的 {{domxref("DocumentType")}} 節點，例如 HTML5 的 <code><!DOCTYPE html></code>。</td> + </tr> + <tr> + <td>{{domxref("Node.DOCUMENT_FRAGMENT_NODE")}} {{readonlyinline}}</td> + <td><code>11</code></td> + <td>A {{domxref("DocumentFragment")}} node.</td> + </tr> + </tbody> +</table> + +<h3 id="已過時的節點類型常數_deprecated_inline()">已過時的節點類型常數 {{deprecated_inline()}}</h3> + +<p>The following constants have been deprecated and should not be used anymore.</p> + +<table class="standard-table"> + <tbody> + <tr> + <td>Constant</td> + <td>Value</td> + <td>Description</td> + </tr> + <tr> + <td><code>Node.ATTRIBUTE_NODE</code></td> + <td>2</td> + <td>An {{domxref("Attr", "Attribute")}} of an {{domxref("Element")}}. The element attributes are no longer implementing the {{domxref("Node")}} interface in {{SpecName("DOM4")}} specification.</td> + </tr> + <tr> + <td><code>Node.CDATA_SECTION_NODE</code></td> + <td><code>4</code></td> + <td>A {{domxref("CDATASection")}}. Removed in {{SpecName("DOM4")}} specification.</td> + </tr> + <tr> + <td><code>Node.ENTITY_REFERENCE_NODE</code></td> + <td>5</td> + <td>An XML Entity Reference node. Removed in {{SpecName("DOM4")}} specification.</td> + </tr> + <tr> + <td><code>Node.ENTITY_NODE</code></td> + <td>6</td> + <td>An XML <code><!ENTITY ...></code> node. Removed in {{SpecName("DOM4")}} specification.</td> + </tr> + <tr> + <td><code>Node.NOTATION_NODE</code></td> + <td>12</td> + <td>An XML <code><!NOTATION ...></code> node. Removed in {{SpecName("DOM4")}} specification.</td> + </tr> + </tbody> +</table> + +<h2 id="Example" name="Example">範例</h2> + +<h3 id="Different_types_of_nodes">Different types of nodes</h3> + +<pre class="brush: js">document.nodeType === Node.DOCUMENT_NODE; // true +document.doctype.nodeType === Node.DOCUMENT_TYPE_NODE; // true + +var fragment = document.createDocumentFragment(); +fragment.nodeType === Node.DOCUMENT_FRAGMENT_NODE; // true + +<code>var p = document.createElement("p"); +p.textContent = "Once upon a time...";</code> + +p.nodeType === Node.ELEMENT_NODE; // true +p.firstChild.nodeType === Node.TEXT_NODE; // true +</pre> + +<h3 id="Comments">Comments</h3> + +<p>This example checks if the first node inside the document element is a comment node, and if it is not, displays a message.</p> + +<pre class="brush: js">var node = document.documentElement.firstChild; +if (node.nodeType != Node.COMMENT_NODE) + console.log("You should comment your code well!"); +</pre> + +<h2 id="Specification" name="Specification">規範</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('DOM WHATWG', '#dom-node-nodetype', 'Node.nodeType')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>Deprecated <code>ATTRIBUTE_NODE, CDATA_SECTION_NODE, ENTITY_REFERENCE_NODE and NOTATION_NODE</code> types.</td> + </tr> + <tr> + <td>{{SpecName('DOM3 Core', 'core.html#ID-1950641247', 'Node.nodeType')}}</td> + <td>{{Spec2('DOM3 Core')}}</td> + <td>No changes.</td> + </tr> + <tr> + <td>{{SpecName('DOM2 Core', 'core.html#ID-111237558', 'Node.nodeType')}}</td> + <td>{{Spec2('DOM2 Core')}}</td> + <td>No changes.</td> + </tr> + <tr> + <td>{{SpecName('DOM1', 'level-one-core.html#ID-111237558', 'Node.nodeType')}}</td> + <td>{{Spec2('DOM1')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> diff --git a/files/zh-tw/web/api/node/ownerdocument/index.html b/files/zh-tw/web/api/node/ownerdocument/index.html new file mode 100644 index 0000000000..33e8e641e8 --- /dev/null +++ b/files/zh-tw/web/api/node/ownerdocument/index.html @@ -0,0 +1,111 @@ +--- +title: Node.ownerDocument +slug: Web/API/Node/ownerDocument +translation_of: Web/API/Node/ownerDocument +--- +<div>{{APIRef("DOM")}}</div> + +<p><code><strong>Node.ownerDocument</strong></code> 唯讀屬性會回傳一個此節點所屬的的頂層 <code>document</code> 物件。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><var>document</var> = <var>element</var>.ownerDocument +</pre> + +<ul> + <li><code>document</code> is the {{domxref("Document", "document")}} object parent of the current element.</li> +</ul> + +<h2 id="範例">範例</h2> + +<pre class="brush:js">// given a node "p", get the top-level HTML child +// of the document object + +var d = p.ownerDocument; +var html = d.documentElement; +</pre> + +<h2 id="備註">備註</h2> + +<p>The <code>document</code> object returned by this property is the main object with which all the child nodes in the actual HTML document are created. If this property is used on a node that is itself a document, the result is <code>null</code>.</p> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th>Specification</th> + <th>Status</th> + <th>Comment</th> + </tr> + <tr> + <td>{{SpecName("DOM4", "#dom-node-ownerdocument", "Node.ownerDocument")}}</td> + <td>{{Spec2("DOM4")}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("DOM3 Core", "core.html#node-ownerDoc", "Node.ownerDocument")}}</td> + <td>{{Spec2("DOM3 Core")}}</td> + <td>No change</td> + </tr> + <tr> + <td>{{SpecName("DOM2 Core", "core.html#node-ownerDoc", "Node.ownerDocument")}}</td> + <td>{{Spec2("DOM2 Core")}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}<sup>[1]</sup></td> + <td>6.0<sup>[2]</sup></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}<sup>[1]</sup></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Starting in Gecko 9.0 {{geckoRelease("9.0")}}, the <code>ownerDocument</code> of doctype nodes (that is, nodes for which {{domxref("Node.nodeType")}} is <code>Node.DOCUMENT_TYPE_NODE</code> or 10) is no longer <code>null</code>. Instead, the <code>ownerDocument</code> is the document on which <a href="/en-US/docs/DOM/DOMImplementation.createDocumentType"><code>document.implementation.createDocumentType()</code></a> was called.</p> + +<p>[2] <a href="http://msdn.microsoft.com/en-us/library/ie/ms534315(v=vs.85).aspx">http://msdn.microsoft.com/en-us/library/ie/ms534315(v=vs.85).aspx</a></p> diff --git a/files/zh-tw/web/api/node/removechild/index.html b/files/zh-tw/web/api/node/removechild/index.html new file mode 100644 index 0000000000..d453835c0c --- /dev/null +++ b/files/zh-tw/web/api/node/removechild/index.html @@ -0,0 +1,133 @@ +--- +title: Node.removeChild() +slug: Web/API/Node/removeChild +translation_of: Web/API/Node/removeChild +--- +<div>{{APIRef("DOM")}}</div> + +<p><code><strong>Node.removeChild()</strong></code> 方法從 DOM 移除一個子節點，並傳回移除的節點。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">var <em>oldChild</em> = <em>node</em>.removeChild(<em>child</em>); +<strong>或</strong> +<em>node</em>.removeChild(<em>child</em>); +</pre> + +<ul> + <li><code>child</code> 是 DOM 中想要移除的子節點。</li> + <li><code>node</code> 是 <code>child</code> 的父節點。</li> + <li><code>oldChild</code> 為將被移除的子節點參照，例如：<code>oldChild === child</code>.</li> +</ul> + +<p>被刪除的子節點仍然存於記憶體之中，只是不在 DOM 了。從上述的第一種語法形式中，我們知道，透過引用 <code>oldChild</code> 還是可以在程式中重新使用已經被移除的子節點。</p> + +<p>而第二種語法形式，因為沒有保留 <code>oldChild</code> 引用，因此假設你並沒有在其他地方保留節點引用，則它會立即無法使用且不可挽回，而且通常會在短時間內從<a href="/en-US/docs/Web/JavaScript/Memory_Management">內存管理</a>中被自動刪除。</p> + +<p>如果 <code>child</code> 並非某 <code>element</code> 節點的子元素，則此方法會拋出異常。而如果調用此方法時，<code>child</code> 雖是某 <code>element</code> 的子元素，但在嘗試刪除它的過程中已被其他事件處理程序刪除，也會拋出異常（例如 {{Event("blur")}}）。</p> + +<h3 id="會丟出的錯誤">會丟出的錯誤</h3> + +<p>兩種不同的方式拋出異常：</p> + +<ol> + <li> + <p>如果 <code>child</code> 確實是 <code>element</code> 的子元素且確實存在於 DOM，但已被刪除，則會丟出以下異常：</p> + + <p><code>Uncaught NotFoundError: Failed to execute 'removeChild' on 'Node': The node to be removed is not a child of this node</code>.</p> + </li> + <li> + <p>如果 <code>child</code> 不存在於頁面的 DOM，則會拋出下列的異常：<br> + <br> + <code>Uncaught TypeError: Failed to execute 'removeChild' on 'Node': parameter 1 is not of type 'Node'.</code></p> + </li> +</ol> + +<h2 id="例子">例子</h2> + +<h3 id="簡單的例子">簡單的例子</h3> + +<p>HTML:</p> + +<pre class="brush: html"><div id="top"> + <div id="nested"></div> +</div> +</pre> + +<p>在知道父節點的情況下，刪除特定元素：</p> + +<pre class="brush:js">let d = document.getElementById("top"); +let d_nested = document.getElementById("nested"); +let throwawayNode = d.removeChild(d_nested); +</pre> + +<p>沒有指定父節點的情況下，刪除特定元素：</p> + +<pre class="brush:js">let node = document.getElementById("nested"); +if (node.parentNode) { + node.parentNode.removeChild(node); +} +</pre> + +<p>從一個元素中移除所有子元素：</p> + +<pre class="brush:js">let element = document.getElementById("top"); +while (element.firstChild) { + element.removeChild(element.firstChild); +} +</pre> + +<h3 id="造成一個TypeError">造成一個TypeError</h3> + +<pre class="brush: html"><!--Sample HTML code--> +<div id="top"> </div> + +<script type="text/javascript"> + let top = document.getElementById("top"); + let nested = document.getElementById("nested"); + + // Throws Uncaught TypeError + let garbage = top.removeChild(nested); +</script> +</pre> + +<h3 id="造成一個NotFoundError">造成一個NotFoundError</h3> + +<pre class="brush: html"><!--Sample HTML code--> +<div id="top"> + <div id="nested"></div> +</div> + +<script type="text/javascript"> + let top = document.getElementById("top"); + let nested = document.getElementById("nested"); + + // This first call correctly removes the node + let garbage = top.removeChild(nested); + + // Throws Uncaught NotFoundError + garbage = top.removeChild(nested); +</script> +</pre> + +<h2 id="規範">規範</h2> + +<ul> + <li><a href="http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#method-removeChild">DOM Level 1 Core: removeChild</a></li> + <li><a href="http://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-1734834066">DOM Level 2 Core: removeChild</a></li> + <li><a href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#ID-1734834066">DOM Level 3 Core: removeChild</a></li> +</ul> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + + + +<p>{{Compat("api.Node.removeChild")}}</p> + +<h2 id="相關連結">相關連結</h2> + +<ul> + <li>{{domxref("Node.replaceChild")}}</li> + <li>{{domxref("Node.parentNode")}}</li> + <li>{{domxref("ChildNode.remove")}}</li> +</ul> diff --git a/files/zh-tw/web/api/node/textcontent/index.html b/files/zh-tw/web/api/node/textcontent/index.html new file mode 100644 index 0000000000..9375396158 --- /dev/null +++ b/files/zh-tw/web/api/node/textcontent/index.html @@ -0,0 +1,158 @@ +--- +title: Node.textContent +slug: Web/API/Node/textContent +translation_of: Web/API/Node/textContent +--- +<div>{{APIRef("DOM")}}</div> + +<p><code><strong>Node.textContent</strong></code> 屬性表示了節點或其後代的文字內容。</p> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox">var <em>text</em> = element.textContent; +element.textContent = "this is some sample text"; +</pre> + +<h2 id="Notes" name="Notes">描述</h2> + +<ul> + <li><code>textContent</code> returns <code>null</code> if the element is a <a href="/en-US/docs/DOM/document" title="DOM/Document">document</a>, a document type, or a notation. To grab all of the text and CDATA data for the whole document, one could use<code> <a href="/en-US/docs/DOM/document.documentElement" title="DOM/document.documentElement">document.documentElement</a>.textContent</code>.</li> + <li>If the node is a CDATA section, a comment, a processing instruction, or a text node, <code>textContent</code> returns the text inside this node (the <a href="/en-US/docs/DOM/Node.nodeValue" title="DOM/Node/NodeValue/Node.nodeValue">nodeValue</a>).</li> + <li>For other node types, <code>textContent</code> returns the concatenation of the <code>textContent</code> attribute value of every child node, excluding comments and processing instruction nodes. This is an empty string if the node has no children.</li> + <li>Setting this property on a node removes all of its children and replaces them with a single text node with the given value.</li> +</ul> + +<h3 id="與_innerText_的差異">與 <code>innerText</code> 的差異</h3> + +<p>Internet Explorer introduced <code>element.innerText</code>. The intention is similar but with the following differences:</p> + +<ul> + <li>While <code>textContent</code> gets the content of all elements, including {{HTMLElement("script")}} and {{HTMLElement("style")}} elements, the IE-specific property <code>innerText</code> does not.</li> + <li><code>innerText</code> is aware of style and will not return the text of hidden elements, whereas textContent will.</li> + <li>As <code>innerText</code> is aware of CSS styling, it will trigger a reflow, whereas <code>textContent</code> will not.</li> + <li>Unlike <code>textContent</code>, altering <code>innerText</code> in Internet Explorer (up to version 11 inclusive) not just removes child nodes from the element, but also <em>permanently destroys</em> all descendant text nodes (so it is impossible to insert the nodes again into any other element or into the same element anymore).</li> +</ul> + +<h3 id="與_innerHTML_的差異">與 <code>innerHTML</code> 的差異</h3> + +<p><code>innerHTML</code> returns the HTML as its name indicates. Quite often, in order to retrieve or write text within an element, people use <code>innerHTML</code>. <code>textContent</code> should be used instead. Because the text is not parsed as HTML, it's likely to have better performance. Moreover, this avoids an <span title="cross-site scripting">XSS</span> attack vector.</p> + +<h2 id="Example" name="Example">範例</h2> + +<pre class="brush: js">// Given the following HTML fragment: +// <div id="divA">This is <span>some</span> text</div> + +// Get the text content: +var text = document.getElementById("divA").textContent; +// |text| is set to "This is some text". + +// Set the text content: +document.getElementById("divA").textContent = "This is some text"; +// The HTML for divA is now: +// <div id="divA">This is some text</div> +</pre> + +<h2 id="Polyfill_for_IE8">Polyfill for IE8</h2> + +<pre class="brush: js">if (Object.defineProperty + && Object.getOwnPropertyDescriptor + && Object.getOwnPropertyDescriptor(Element.prototype, "textContent") + && !Object.getOwnPropertyDescriptor(Element.prototype, "textContent").get) { + (function() { + var innerText = Object.getOwnPropertyDescriptor(Element.prototype, "innerText"); + Object.defineProperty(Element.prototype, "textContent", + { + get: function() { + return innerText.get.call(this); + }, + set: function(s) { + return innerText.set.call(this, s); + } + } + ); + })(); +} +</pre> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>1+</td> + <td>2</td> + <td>9</td> + <td>9.64 (possibly earlier)</td> + <td>3 (possibly earlier)</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="Specifications" name="Specifications">規範</h2> + +<table class="spectable standard-table"> + <tbody> + <tr> + <th scope="col">Specification</th> + <th scope="col">Status</th> + <th scope="col">Comment</th> + </tr> + <tr> + <td>{{SpecName('DOM WHATWG','#dom-node-textcontent','Node.textContent')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>No changes versus DOM4</td> + </tr> + <tr> + <td>{{SpecName('DOM4','#dom-node-textcontent','Node.textContent')}}</td> + <td>{{Spec2('DOM4')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM3 Core','core.html#Node3-textContent','Node.textContent')}}</td> + <td>{{Spec2('DOM3 Core')}}</td> + <td>Introduced</td> + </tr> + </tbody> +</table> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="http://perfectionkills.com/the-poor-misunderstood-innerText/">More on differences between <code>innerText</code> and <code>textContent</code></a> (blog post)</li> +</ul> diff --git a/files/zh-tw/web/api/nodelist/index.html b/files/zh-tw/web/api/nodelist/index.html new file mode 100644 index 0000000000..f431bd1761 --- /dev/null +++ b/files/zh-tw/web/api/nodelist/index.html @@ -0,0 +1,219 @@ +--- +title: NodeList +slug: Web/API/NodeList +translation_of: Web/API/NodeList +--- +<div>{{APIRef("DOM")}}</div> + +<p><strong><code>NodeList</code></strong> 物件是節點的集合，可藉由 {{domxref("Node.childNodes")}} 屬性以及 {{domxref("document.querySelectorAll()")}} 方法取得。</p> + +<div class="note"> +<p>雖然 <code>NodeList</code> 不是 <code>Array</code>，但仍可以使用 <code>forEach()</code> 方法來進行迭代。一些老舊瀏覽器並未實作此方法。</p> +</div> + +<p>在某些情況下，<code>NodeList</code> 為<em>動態集合（live collection）</em>，意思是 DOM 的改變會反映於集合。例如，{{domxref("Node.childNodes")}} 便是即時更新（live）的：</p> + +<pre class="brush: js">var parent = document.getElementById('parent'); +var child_nodes = parent.childNodes; +console.log(child_nodes.length); // let's assume "2" +parent.appendChild(document.createElement('div')); +console.log(child_nodes.length); // should output "3" +</pre> + +<p>在其他的情況下，<code>NodeList</code> 是一個<em>靜態的集合（static collection）</em>，代表任何之後的 DOM 變化都不會影響集合的內容。{{domxref("document.querySelectorAll()")}} 會回傳一個靜態的 <code>NodeList</code>。</p> + +<p>當你要選擇如何迭代 <code>NodeList</code> 中的項目時，最好能於心中區分動態與靜態集合，尤其是在取得集合長度（length of the list）的時候。</p> + +<h2 id="屬性">屬性</h2> + +<dl> + <dt>{{domxref("NodeList.length")}}</dt> + <dd>The number of nodes in the <code>NodeList</code>.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<dl> + <dt>{{domxref("NodeList.item()")}}</dt> + <dd>Returns an item in the list by its index, or <code>null</code> if the index is out-of-bounds; can be used as an alternative to simply accessing <code>nodeList[idx]</code> (which instead returns <code>undefined</code> when <code>idx</code> is out-of-bounds).</dd> + <dt>{{domxref("NodeList.entries()")}}</dt> + <dd>Returns an {{jsxref("Iteration_protocols","iterator")}} allowing to go through all key/value pairs contained in this object.</dd> + <dt>{{domxref("NodeList.forEach()")}}</dt> + <dd>Executes a provided function once per <code>NodeList</code> element.</dd> + <dt>{{domxref("NodeList.keys()")}}</dt> + <dd>Returns an {{jsxref("Iteration_protocols", "iterator")}} allowing to go through all keys of the key/value pairs contained in this object.</dd> + <dt>{{domxref("NodeList.values()")}}</dt> + <dd>Returns an {{jsxref("Iteration_protocols", "iterator")}} allowing to go through all values of the key/value pairs contained in this object.</dd> +</dl> + +<h2 id="範例">範例</h2> + +<p>It's possible to loop over the items in a <code>NodeList</code> using:</p> + +<pre class="brush: js">for (var i = 0; i < myNodeList.length; ++i) { + var item = myNodeList[i]; // Calling myNodeList.item(i) isn't necessary in JavaScript +} +</pre> + +<p>Don't be tempted to use <code><a href="/en-US/docs/JavaScript/Reference/Statements/for...in" title="JavaScript/ Reference/Statements/for...in">for...in</a></code> or <code><a href="/en-US/docs/JavaScript/Reference/Statements/for_each...in" title="JavaScript/ Reference/Statements/for each...in">for each...in</a></code> to enumerate the items in the list, since that will also enumerate the length and item properties of the <code>NodeList</code> and cause errors if your script assumes it only has to deal with {{domxref("element")}} objects. Also, <code>for..in</code> is not guaranteed to visit the properties in any particular order.</p> + +<p><code><a href="/en-US/docs/JavaScript/Reference/Statements/for...of" title="/en-US/docs/JavaScript/Reference/Statements/for...of">for...of</a></code> loops will loop over <code>NodeList</code> objects correctly:</p> + +<pre class="brush: js">var list = document.querySelectorAll( 'input[type=checkbox]' ); +for (var item of list) { + item.checked = true; +}</pre> + +<p>Recent browsers also support iterator methods, {{domxref("NodeList.forEach()", "forEach()")}}, as well as {{domxref("NodeList.entries()", "entries()")}}, {{domxref("NodeList.values()", "values()")}}, and {{domxref("NodeList.keys()", "keys()")}}</p> + +<p>There is also an Internet Explorer compatible way to use {{jsxref("Array.forEach()", "Array.prototype.forEach")}} for iteration.</p> + +<pre class="brush: js">var list = document.querySelectorAll( 'input[type=checkbox]' ); +Array.prototype.forEach.call(list, function (item) { + item.checked = true; +});</pre> + +<h2 id="Specifications" name="Specifications">NodeList 原型</h2> + +<p>You can also add prototypes to nodelist:</p> + +<pre class="brush: js">var elements = document.querySelectorAll(".suggestions"); + +NodeList.prototype.addEventListener = function(event, func) { + this.forEach(function(content, item) { + content.addEventListener(event, func); + }); +} + +function log() { + console.log(this, " was clicked"); +} + +elements.addEventListener("click", log); +//or +elements.addEventListener("click", function() { + console.log(this, " awas clicked"); +}); +// output from both will be <em>element </em>was clicked the element would be HTML Element</pre> + +<p>For information about forEach see <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach" title="Web/JavaScript/Reference/Global_Objects/Array/forEach">Array.prototype.forEach()</a></p> + +<h2 id="Specifications" name="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('DOM WHATWG', '#interface-nodelist', 'NodeList')}}</td> + <td>{{ Spec2('DOM WHATWG') }}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM4', '#interface-nodelist', 'NodeList')}}</td> + <td>{{ Spec2('DOM4') }}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM3 Core', 'core.html#ID-536297177', 'NodeList')}}</td> + <td>{{ Spec2('DOM3 Core') }}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM2 Core', 'core.html#ID-536297177', 'NodeList')}}</td> + <td>{{ Spec2('DOM2 Core') }}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('DOM1', 'level-one-core.html#ID-536297177', 'NodeList')}}</td> + <td>{{ Spec2('DOM1') }}</td> + <td>Initial definition.</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>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>entries()</code>, <code>keys()</code>, <code>values()</code>, <code>forEach()</code></td> + <td>{{CompatChrome(51)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop(50)}}</td> + <td>{{CompatNo}}</td> + <td>38</td> + <td>10 (maybe prior)</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>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>entries()</code>, <code>keys()</code>, <code>values()</code>, <code>forEach()</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile(50)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>10 (maybe prior)</td> + <td>{{CompatChrome(51)}}</td> + </tr> + </tbody> +</table> +</div> diff --git a/files/zh-tw/web/api/nondocumenttypechildnode/index.html b/files/zh-tw/web/api/nondocumenttypechildnode/index.html new file mode 100644 index 0000000000..31fb8c91e5 --- /dev/null +++ b/files/zh-tw/web/api/nondocumenttypechildnode/index.html @@ -0,0 +1,125 @@ +--- +title: NonDocumentTypeChildNode +slug: Web/API/NonDocumentTypeChildNode +translation_of: Web/API/NonDocumentTypeChildNode +--- +<div>{{APIRef("DOM")}}</div> + +<p><code><strong>NonDocumentTypeChildNode</strong></code> 介面定義了可以擁有父節點但不適用 {{domxref("DocumentType")}} 之 {{domxref("Node")}} 物件的方法。</p> + +<p><code>NonDocumentTypeChildNode</code> 是一個原始的介面，且不能以此建立物件實體。{{domxref("Element")}} 及 {{domxref("CharacterData")}} 物件皆實作了 <code>NonDocumentTypeChildNode</code>。</p> + +<h2 id="屬性">屬性</h2> + +<p><em>There is no inherited property.</em></p> + +<dl> + <dt>{{domxref("NonDocumentTypeChildNode.previousElementSibling")}} {{readonlyInline}}</dt> + <dd>Returns the {{domxref("Element")}} immediately prior to this node in its parent's children list, or <code>null</code> if there is no {{domxref("Element")}} in the list prior to this node.</dd> + <dt>{{domxref("NonDocumentTypeChildNode.nextElementSibling")}} {{readonlyInline}}</dt> + <dd>Returns the {{domxref("Element")}} immediately following this node in its parent's children list, or <code>null</code> if there is no {{domxref("Element")}} in the list following this node.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>There is neither inherited, nor specific method.</em></p> + +<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('DOM WHATWG', '#interface-childnode', 'NonDocumentTypeChildNode')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>Splitted the <code>ElementTraversal</code> interface in {{domxref("ParentNode")}}, {{domxref("ChildNode")}}, and <code>NonDocumentTypeChildNode</code>. The <code>previousElementSibling</code> and <code>nextElementSibling</code> are now defined on the latter.<br> + The {{domxref("CharacterData")}} and {{domxref("Element")}} implemented the new interfaces.</td> + </tr> + <tr> + <td>{{SpecName('Element Traversal', '#interface-elementTraversal', 'ElementTraversal')}}</td> + <td>{{Spec2('Element Traversal')}}</td> + <td>Added the initial definition of its properties to the <code>ElementTraversal</code> pure interface and use it on {{domxref("Element")}}.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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 (on {{domxref("Element")}})</td> + <td>1.0</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9.0</td> + <td>10.0</td> + <td>4.0</td> + </tr> + <tr> + <td>Support (on {{domxref("CharacterData")}})</td> + <td>1.0</td> + <td>{{CompatGeckoDesktop("25.0")}} [1]</td> + <td>9.0</td> + <td>10.0</td> + <td>4.0</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support (on {{domxref("Element")}})</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>10.0</td> + <td>{{ CompatVersionUnknown() }}</td> + </tr> + <tr> + <td>Support (on {{domxref("CharacterData")}})</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{CompatGeckoDesktop("25.0")}}</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>10.0</td> + <td>{{ CompatVersionUnknown() }}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Firefox 25 also added the two properties defined here on {{domxref("DocumentType")}}, this was removed in Firefox 28 due to compatibility problems, and led to the creation of this new pure interface.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>The {{domxref("ParentNode")}} and {{domxref("ChildNode")}} pure interface.</li> + <li> + <div class="syntaxbox">Object types implementing this pure interface: {{domxref("CharacterData")}}, and {{domxref("Element")}}.</div> + </li> +</ul> diff --git a/files/zh-tw/web/api/notification/index.html b/files/zh-tw/web/api/notification/index.html new file mode 100644 index 0000000000..fc1e0f9434 --- /dev/null +++ b/files/zh-tw/web/api/notification/index.html @@ -0,0 +1,355 @@ +--- +title: Notification +slug: Web/API/notification +tags: + - 待翻譯 +translation_of: Web/API/Notification +--- +<p>{{APIRef("Web Notifications")}}</p> + +<p><a href="/zh-TW/docs/Web/API/Notifications_API">Notifications API</a> 的 <code>Notification</code> interface 是用來設置及顯示「桌面通知」給使用。</p> + +<p>{{AvailableInWorkers}}</p> + +<h2 id="Constructor">Constructor</h2> + +<dl> + <dt>{{domxref("Notification.Notification", "Notification()")}}</dt> + <dd>建立一個新的 {{domxref('Notification')}} 實例。</dd> +</dl> + +<h2 id="Properties">Properties</h2> + +<h3 id="靜態屬性">靜態屬性</h3> + +<p>以下的屬性僅適用於 <code>Notification</code> 實例。</p> + +<dl> + <dt>{{domxref("Notification.permission")}} {{readonlyinline}}</dt> + <dd>一個表示允許通知顯示與否的權限的 string。可能的值有：「denied」(使用者不允許顯示 Notification )、「granted」(使用者允許顯示 Notification )，或者是「default」(還不知道使用者允許與否，預設行為與 denied 一致)。</dd> +</dl> + +<h3 id="實例屬性">實例屬性</h3> + +<p>以下屬應僅適用於 <code>Notification</code> 實例。</p> + +<dl> + <dt>{{domxref("Notification.title")}} {{readonlyinline}}</dt> + <dd>在建構子的 options 參數中指定的 Notification 的標題。</dd> + <dt>{{domxref("Notification.dir")}} {{readonlyinline}}</dt> + <dd>在建構子的 options 參數中指定的 Notification 的文字顯示方向。</dd> + <dt>{{domxref("Notification.lang")}} {{readonlyinline}}</dt> + <dd>在建構子的 options 參數中指定的 Notification 的語言代號。</dd> + <dt>{{domxref("Notification.body")}} {{readonlyinline}}</dt> + <dd>在建構子的 options 參數中指定的 Notification 的內容。</dd> + <dt>{{domxref("Notification.tag")}} {{readonlyinline}}</dt> + <dd>The ID of the notification (if any) as specified in the options parameter of the constructor.</dd> + <dt>{{domxref("Notification.icon")}} {{readonlyinline}}</dt> + <dd>在建構子的 options 參數中指定的 Notification 的 icon 的網址。</dd> + <dt>{{domxref("Notification.data")}} {{readonlyinline}}</dt> + <dd>回傳結構化的 Notification 的資料。</dd> + <dt>{{domxref("Notification.requireInteraction")}} {{readonlyinline}}</dt> + <dd>一個 {{jsxref("Boolean")}} 指示在有充足大小的螢幕上的時候，Notfication 實例是否會持續顯示直到使用者點擊它或者 dismisses it。</dd> + <dt>{{domxref("Notification.silent")}} {{readonlyinline}}</dt> + <dd>表示 Notfication 是否設定要以較低調的方式呈現(比如不撥放通知音效、不震動)。這個設定與裝置本身的設定無關。</dd> +</dl> + +<dl> + <dt>{{domxref("Notification.timestamp")}} {{readonlyinline}}</dt> + <dd>表示 Notification 的建立時間、或者可啟動的時間 (可能是過去、現在或未來)。</dd> +</dl> + +<dl> + <dt>{{domxref("Notification.vibrate")}} {{readonlyinline}}</dt> + <dd>表示在可震動的裝置上的震動模式。</dd> +</dl> + +<h4 id="尚未支援的屬性">尚未支援的屬性</h4> + +<p>The following properties are listed in the most up-to-date spec, but are not supported in any browsers yet. It is advisable to keep checking back regularly to see if the status of these has updated, and let us know if you find any out of date information.</p> + +<dl> + <dt>{{domxref("Notification.noscreen")}} {{readonlyinline}}</dt> + <dd>表示 Notification 顯示時是否要打開裝置的螢幕。</dd> + <dt>{{domxref("Notification.renotify")}} {{readonlyinline}}</dt> + <dd>表示使用者是否會在舊的 Notification 被新的 Notification 替換掉時通知。</dd> + <dt>{{domxref("Notification.sound")}} {{readonlyinline}}</dt> + <dd>表示當 Notification 顯示時要用來代替系統預設音效撥放的音訊資源。</dd> + <dt>{{domxref("Notification.sticky")}} {{readonlyinline}}</dt> + <dd>表示 Notification 是否「sticky」(比如使用者不太容易清除它)。</dd> +</dl> + +<h4 id="事件處理器">事件處理器</h4> + +<dl> + <dt>{{domxref("Notification.onclick")}}</dt> + <dd>一個 {{event("click")}} 事件的 handler。每次使用者點擊 Notification 都會被觸發。</dd> + <dt>{{domxref("Notification.onerror")}}</dt> + <dd>一個 {{event("error")}} 事件的 handler. 每次 Notification 發生 Error 都會被觸發。</dd> +</dl> + +<h4 id="停止支援的事件處理器">停止支援的事件處理器</h4> + +<p>底下這些列在 {{anch("browser compatibility")}} 中的 event handlers 雖然還有支援，但已經從近期的 spec 中移除了。因為瀏覽器會在未來的版本逐漸停止支援，最好還是不要使用它們。</p> + +<dl> + <dt>{{domxref("Notification.onclose")}}</dt> + <dd>A handler for the {{event("close")}} event. It is triggered when the user closes the notification.</dd> + <dt>{{domxref("Notification.onshow")}}</dt> + <dd>A handler for the {{event("show")}} event. It is triggered when the notification is displayed.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<h3 id="靜態方法">靜態方法</h3> + +<p>這些方法只能在<code> Notification 實例上使用。</code></p> + +<dl> + <dt>{{domxref("Notification.requestPermission()")}}</dt> + <dd>向使用者詢問是否開放顯示 Notification 的權限。</dd> +</dl> + +<h3 id="實例方法">實例方法</h3> + +<p>These properties are available only on an instance of the <code>Notification</code> object or through its <a href="/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain"><code>prototype</code></a>. The <code>Notification</code> object also inherits from the {{domxref("EventTarget")}} interface.</p> + +<dl> + <dt>{{domxref("Notification.close()")}}</dt> + <dd>透過這個方法關閉 Notification 。</dd> +</dl> + +<h2 id="範例">範例</h2> + +<p>先看這段基本的 HTML：</p> + +<pre class="brush: html"><button onclick="notifyMe()">Notify me!</button></pre> + +<p>用下面的程式碼我們可以送出通知： 底下的程式碼雖然略嫌冗長，但完整的示範了如何在送出通知之前，事先檢查了瀏覽器是否支援 Notification、使用者是否授權這個網域的網頁送出通知，以及在需要的時候向使用者詢問是否開放權限。</p> + +<pre class="brush: js">function notifyMe() { + // 首先讓我們確定瀏覽器支援 Notification + if (!("Notification" in window)) { + alert("這個瀏覽器不支援 Notification"); + } + + // 再檢查使用者是否已經授權執行 Notification + else if (Notification.permission === "granted") { + // 如果已經授權就可以直接新增 Notification 了! + var notification = new Notification("安安你好!"); + } + + // 否則，我們會需要詢問使用者是否開放權限 + else if (Notification.permission !== 'denied') { + Notification.requestPermission(function (permission) { + // 如果使用者同意了就來新增一個 Notification 打聲招呼吧 + if (permission === "granted") { + var notification = new Notification("安安~"); + } + }); + } + + // 如果使用者還是不同意授權執行 Notification + // 最好還是進行適當的處理以避免繼續打擾使用者 +}</pre> + +<p>{{EmbedLiveSample('範例', '100%', 30)}}</p> + +<p>在很多時候，你應該不會想要這麼冗長的程式碼。 比如說，在我們的 <a href="http://mdn.github.io/emogotchi/">Emogotchi demo</a> (<a href="https://github.com/mdn/emogotchi">see source code</a>) 之中，我們只寫了 {{domxref("Notification.requestPermission")}} 而不用進一步檢查是否已經獲得了權限：</p> + +<pre class="brush: js">Notification.requestPermission();</pre> + +<p>然後我們只需要在要新增 Notfication 時執行這個 <code>spawnNotification()</code> — 透過傳入指定的 body、icon、title，然後它就會產生我們所需的 options 參數並透過 {{domxref("Notification.Notification","Notification()")}} 建構子發送 Notification.</p> + +<pre class="brush: js">function spawnNotification(theBody,theIcon,theTitle) { + var options = { + body: theBody, + icon: theIcon + } + var n = new Notification(theTitle,options); +}</pre> + +<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('Web Notifications')}}</td> + <td>{{Spec2('Web Notifications')}}</td> + <td>Living standard</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器支援度">瀏覽器支援度</h2> + +<p>{{CompatibilityTable}}</p> + +<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>5{{property_prefix("webkit")}}<sup>[1]</sup><br> + 22</td> + <td>4.0 {{property_prefix("moz")}}<sup>[2]</sup><br> + 22</td> + <td>{{CompatNo}}</td> + <td>25</td> + <td>6<sup>[3]</sup></td> + </tr> + <tr> + <td><code>icon</code></td> + <td>5{{property_prefix("webkit")}}<sup>[1]</sup><br> + 22</td> + <td>4.0 {{property_prefix("moz")}}<sup>[2]</sup><br> + 22</td> + <td>{{CompatNo}}</td> + <td>25</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>Available in workers</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoDesktop("41.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>silent</code></td> + <td>{{CompatChrome(43.0)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>noscreen</code>, <code>renotify</code>, <code>sound</code>, <code>sticky</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</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</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>{{CompatUnknown}}</td> + <td> + <p>{{CompatVersionUnknown}}</p> + </td> + <td>4.0{{property_prefix("moz")}}<sup>[2]</sup><br> + 22</td> + <td>1.0.1{{property_prefix("moz")}}<sup>[2]</sup><br> + 1.2</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td> + <p>{{CompatVersionUnknown}}</p> + </td> + </tr> + <tr> + <td><code>icon</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>4.0{{property_prefix("moz")}}<sup>[2]</sup><br> + 22</td> + <td>1.0.1{{property_prefix("moz")}}<sup>[2]</sup><br> + 1.2</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>Available in workers</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("41.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>silent</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatChrome(43.0)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatChrome(43.0)}}</td> + </tr> + <tr> + <td><code>noscreen</code>, <code>renotify</code>, <code>sound</code>, <code>sticky</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Before Chrome 22, the support for notification followed an <a href="http://www.chromium.org/developers/design-documents/desktop-notifications/api-specification">old prefixed version of the specification</a> and used the {{domxref("window.navigator.webkitNotifications","navigator.webkitNotifications")}} object to instantiate a new notification.</p> + +<p>Before Chrome 32, {{domxref("Notification.permission")}} was not supported.</p> + +<p>Before Chrome 42, service worker additions were not supported.</p> + +<p>[2] Prior to Firefox 22 (Firefox OS <1.2), the instantiation of a new notification must be done with the {{domxref("window.navigator.mozNotification", "navigator.mozNotification")}} object through its <code>createNotification</code> method.</p> + +<p>Prior to Firefox 22 (Firefox OS <1.2), the Notification was displayed when calling the <code>show</code> method and supported only the <code>click</code> and <code>close</code> events.</p> + +<p>Nick Desaulniers wrote a <a href="https://github.com/nickdesaulniers/fxos-irc/blob/master/js/notification.js">Notification shim</a> to cover both newer and older implementations.</p> + +<p>One particular Firefox OS issue is that you can <a href="https://github.com/nickdesaulniers/fxos-irc/blob/0160cf6c3a2b5c9fe33822aaf6bcba3b7e846da9/my.js#L171">pass a path to an icon</a> to use in the notification, but if the app is packaged you cannot use a relative path like <code>/my_icon.png</code>. You also can't use <code>window.location.origin + "/my_icon.png"</code> because <code>window.location.origin</code> is null in packaged apps. The <a href="https://developer.mozilla.org/en-US/Apps/Developing/Manifest#origin">manifest origin field</a> fixes this, but it is only available in Firefox OS 1.1+. A potential solution for supporting Firefox OS <1.1 is to <a href="https://github.com/nickdesaulniers/fxos-irc/blob/0160cf6c3a2b5c9fe33822aaf6bcba3b7e846da9/my.js#L168">pass an absolute URL to an externally hosted version of the icon</a>. This is less than ideal as the notification is displayed immediately without the icon, then the icon is fetched, but it works on all versions of Firefox OS.</p> + +<p>When using notifications in a Firefox OS app, be sure to add the <code>desktop-notification</code> permission in your manifest file. Notifications can be used at any permission level, hosted or above: <code>"permissions": { "desktop-notification": {} }</code></p> + +<p>[3] Safari started to support notification with Safari 6, but only on Mac OSX 10.8+ (Mountain Lion).</p> + +<h2 id="延伸閱讀">延伸閱讀</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/Notifications_API/Using_the_Notifications_API">Using the Notifications API</a></li> +</ul> diff --git a/files/zh-tw/web/api/notifications_api/index.html b/files/zh-tw/web/api/notifications_api/index.html new file mode 100644 index 0000000000..8cf3276371 --- /dev/null +++ b/files/zh-tw/web/api/notifications_api/index.html @@ -0,0 +1,198 @@ +--- +title: Notifications API +slug: Web/API/Notifications_API +translation_of: Web/API/Notifications_API +--- +<p>{{DefaultAPISidebar("Web Notifications")}}</p> + +<p class="summary"><span class="tlid-translation translation" lang="zh-TW"><span title="">Notifications API允許網頁控制向終端用戶顯示系統通知</span></span> — 它在網頁瀏覽器的視圖之外，因此使用者切換顯示卡或移至不同的應用程式也能顯示。此 API 設計為在相容於不同平台與現有的通知系統相容。</p> + +<h2 id="概念與使用方法">概念與使用方法</h2> + +<p><span class="tlid-translation translation" lang="zh-TW"><span title="">在受到支持的平台上，顯示系統通知通常涉及兩件事。</span></span> <span class="tlid-translation translation" lang="zh-TW"><span title="">首先，用戶需要授予當前的來源權限才能顯示系統通知，</span></span><span class="tlid-translation translation" lang="zh-TW"><span title="">通常在應用程式或網站初始化完成後</span></span>使用{{domxref("Notification.requestPermission()")}} 方法。</p> + +<pre class="brush: js">btn.addEventListener('click', function() { + let promise = Notification.requestPermission(); + // wait for permission +})</pre> + +<p>這不僅是最佳實踐 — <span class="tlid-translation translation" lang="zh-TW"><span title="">您不應向用戶發送他們不同意的通知，並且在未來瀏覽器將明確禁止沒有響應用戶請求允許通知對話框的通知。Firefox 72 開始已遵循這項約定。使用此方法將產生一個請求對話框，如下所示：</span></span></p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/10819/notification-bubble.png" style="display: block; height: 205px; margin: 0 auto; width: 453px;"></p> + +<p><span class="tlid-translation translation" lang="zh-TW"><span title="">用戶可以從此處選擇允許、屏蔽來自此來源的通知，也可以不做選擇。</span> <span title="">一旦選定，該設置通常將在當前會話中保持不變。</span></span></p> + +<div class="note"> +<p><strong>注意</strong>: 從 Firefox 44 開始，Notifications 和 <a href="/en-US/docs/Web/API/Push_API">Push</a> 的權限已合併。如果授予通知權限則推送也將被啟用。</p> +</div> + +<p>下一步，使用 {{domxref("Notification.Notification","Notification()")}} 構造函數創建一個新通知。 這必須要傳遞一個標題參數(title)，並且可以選擇性的傳遞選擇物件指定諸如文字方向、正文、圖標、撥放通知的聲音等等。</p> + +<p>{{AvailableInWorkers}}</p> + +<p><span class="tlid-translation translation" lang="zh-TW"><span title="">另外，Notifications API規範指定了</span></span> <a href="/en-US/docs/Web/API/ServiceWorker_API">ServiceWorker API</a> <span class="tlid-translation translation" lang="zh-TW"><span title="">的許多附加功能，以允許服務人員觸發通知。</span></span></p> + +<div class="note"> +<p><strong>注意</strong>: <span class="tlid-translation translation" lang="zh-TW"><span title="">要了解有關在自己的應用程序中使用通知的更多信息，請閱讀</span></span> <a href="/en-US/docs/Web/API/Notifications_API/Using_the_Notifications_API">Using the Notifications API</a>。</p> +</div> + +<h2 id="Notifications_介面">Notifications 介面</h2> + +<dl> + <dt>{{domxref("Notification")}}</dt> + <dd>定義一個通知物件。</dd> +</dl> + +<h3 id="Service_worker_附加功能">Service worker 附加功能</h3> + +<dl> + <dt>{{domxref("ServiceWorkerRegistration")}}</dt> + <dd>包含 {{domxref("ServiceWorkerRegistration.showNotification()")}} 和 {{domxref("ServiceWorkerRegistration.getNotifications()")}} <span class="tlid-translation translation" lang="zh-TW"><span title="">用於控制通知顯示的方法。</span></span></dd> + <dt>{{domxref("ServiceWorkerGlobalScope")}}</dt> + <dd>包含 {{domxref("ServiceWorkerGlobalScope.onnotificationclick")}} <span class="tlid-translation translation" lang="zh-TW"><span title="">點擊通知時觸發自定義函數的處理程序。</span></span></dd> + <dt>{{domxref("NotificationEvent")}}</dt> + <dd>基於 {{domxref("ExtendableEvent")}} <span class="tlid-translation translation" lang="zh-TW"><span title="">的特定類型的事件對象，它表示已觸發的通知。</span></span></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('Web Notifications')}}</td> + <td>{{Spec2('Web Notifications')}}</td> + <td>Living standard</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>5{{property_prefix("webkit")}}<sup>[1]</sup><br> + 22</td> + <td>{{CompatGeckoDesktop("2.0")}}{{property_prefix("moz")}}<sup>[2]</sup><br> + {{CompatGeckoDesktop("22.0")}}</td> + <td>{{CompatNo}}</td> + <td>25</td> + <td>6<sup>[3]</sup></td> + </tr> + <tr> + <td>Available in workers</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoDesktop("41.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>Service worker additions</td> + <td> + <p>{{CompatChrome(42.0)}}</p> + </td> + <td>{{CompatGeckoDesktop("42.0")}}<sup>[4]</sup></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</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</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>{{CompatUnknown}}</td> + <td> + <p>{{CompatVersionUnknown}}</p> + </td> + <td>{{CompatGeckoMobile(2.0)}}{{property_prefix("moz")}}<sup>[2]</sup><br> + {{CompatGeckoMobile(22.0)}}</td> + <td>1.0.1{{property_prefix("moz")}}<sup>[2]</sup><br> + 1.2</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td> + <p>{{CompatVersionUnknown}}</p> + </td> + </tr> + <tr> + <td>Available in workers</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile(41.0)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>Service worker additions</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile(42.0)}}<sup>[4]</sup></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatChrome(42.0)}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Before Chrome 22, the support for notification followed an <a href="http://www.chromium.org/developers/design-documents/desktop-notifications/api-specification">old prefixed version of the specification</a> and used the {{domxref("window.navigator.webkitNotifications","navigator.webkitNotifications")}} object to instantiate a new notification. Before Chrome 32, {{domxref("Notification.permission")}} was not supported.</p> + +<p>[2] Prior to Firefox 22 (Firefox OS <1.2), the instantiation of a new notification was done with the {{domxref("window.navigator.mozNotification", "navigator.mozNotification")}} object through its <code>createNotification()</code> method. In addition, the Notification was displayed when calling the <code>show()</code> method and supported only the <code>click</code> and <code>close</code> events (Nick Desaulniers wrote a <a href="https://github.com/nickdesaulniers/fxos-irc/blob/master/js/notification.js">Notification shim</a> to cover both newer and older implementations.)</p> + +<p>[3] Safari started to support notification with Safari 6, but only on Mac OSX 10.8+ (Mountain Lion).</p> + +<p>[4] Firefox 42 has shipped with web notifications from Service Workers disabled.</p> + +<h2 id="Firefox_OS_permissions">Firefox OS permissions</h2> + +<p>When using notifications in a Firefox OS app, be sure to add the <code>desktop-notification</code> permission in your manifest file. Notifications can be used at any permission level, hosted or above:</p> + +<pre class="brush: json">"permissions": { + "desktop-notification": {} +}</pre> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/Notifications_API/Using_the_Notifications_API">Using the Notifications API</a></li> +</ul> diff --git a/files/zh-tw/web/api/notifications_api/using_the_notifications_api/index.html b/files/zh-tw/web/api/notifications_api/using_the_notifications_api/index.html new file mode 100644 index 0000000000..1a970509c2 --- /dev/null +++ b/files/zh-tw/web/api/notifications_api/using_the_notifications_api/index.html @@ -0,0 +1,236 @@ +--- +title: 使用 Web Notifications +slug: Web/API/Notifications_API/Using_the_Notifications_API +translation_of: Web/API/Notifications_API/Using_the_Notifications_API +--- +<p>{{SeeCompatTable}}</p> + +<h2 id="摘要">摘要</h2> + +<p>Web Notifications API 可將通知傳送至頁面以外的系統層級並顯示通知。因此即使 Web Apps 處於閒置狀態，亦可傳送資訊予使用者。絕佳範例之一，就是在使用其他 Apps 時，Web Mail App 同樣可通知使用者已接收到新郵件。</p> + +<h2 id="要求權限">要求權限</h2> + +<h3 id="網頁內容">網頁內容</h3> + +<p>在 Apps 傳送通知之前，使用者必須先許可 Apps 的動作。只要 APIs 嘗試予網頁之外的東西互動，均必須先獲得使用者的授權。如此可避免濫發通知而影響使用經驗。</p> + +<p>透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification.permission" title="The permission property indicates the current permission granted by the user about web notification for the current application."><code>Notification.permission</code></a> 唯讀屬性，要傳送通知的 Apps 將檢查目前的授權狀態。此屬性共有 3 組參數：</p> + +<ul> + <li><code>default：</code>使用者尚未給予任何權限 (因此不會顯示任何通知)</li> + <li><code>granted</code>：使用者允許接收到 Apps 的通知</li> + <li><code>denied</code><code>：使用者拒絕接收 </code>Apps 的通知</li> +</ul> + +<div class="note"> +<p><strong>注意：</strong>Chrome 與 Safari 尚未建構 <code>permission</code> 屬性。</p> +</div> + +<p>若使用者尚未給予權限，則 Apps 必須透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification.requestPermission" title="The requestPermission static method is used to ask the user for his permission to display a Notification to him."><code>Notification.requestPermission()</code></a> 函式讓使用者選擇，接著由此函式接收 1 組回呼 (Callback) 函式作為參數；而該回呼函式則提供使用者是否授權的資訊。</p> + +<p>以下為啟動 Apps 時要求權限的常用範例：</p> + +<pre class="brush: js">window.addEventListener('load', function () { + Notification.requestPermission(function (status) { + // This allows to use Notification.permission with Chrome/Safari + if (Notification.permission !== status) { + Notification.permission = status; + } + }); +});</pre> + +<div class="note"> +<p><strong>注意：</strong>Chrome 不允許於載入事件中呼叫 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification.requestPermission" title="The requestPermission static method is used to ask the user for his permission to display a Notification to him."><code>Notification.requestPermission()</code></a> (參閱 <a href="https://code.google.com/p/chromium/issues/detail?id=274284" title="https://code.google.com/p/chromium/issues/detail?id=274284">issue 274284</a>)。</p> +</div> + +<h3 id="已安裝的_Apps">已安裝的 Apps</h3> + +<p>在安裝 Apps 之後，若於 <a href="https://developer.mozilla.org/zh-TW/docs/%E6%87%89%E7%94%A8%E7%A8%8B%E5%BC%8F/Manifest-840092-dup" title="/en-US/docs/Web/Apps/Manifest">Apps 的 manifest 檔案</a>中直接添加權限，即可省去再次向使用者要求權限的動作。</p> + +<pre class="brush: json">permissions: { + "desktop-notification": { + "description: "Allows to display notifications on the user's desktop. + } +}</pre> + +<h2 id="建立通知">建立通知</h2> + +<p>透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification" title="The Notification object is used to configure and display desktop notifications to the user."><code>Notification</code></a> 建構子 (Constructor) 即可建立通知。此建構子包含 1 組標題，可於通知內顯示；另有如 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification.icon" title="The icon property indicates the URL of the icon to use with the notification."><code>icon</code></a> 或文字 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification.body" title="The body property represents the text content of the body of the notification."><code>body</code></a><code> 等</code>數個選項，可強化通知的內容。</p> + +<p>在建立實體 (Instantiated) 之後，就會儘快顯示通知。若要追蹤通知的目前狀態，必須在 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification" title="The Notification object is used to configure and display desktop notifications to the user."><code>Notification</code></a> 的實體階層觸發 4 個事件：</p> + +<ul> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/Reference/Events/show" title="/en-US/docs/Web/Reference/Events/show">show</a>：對使用者顯示通知之後，隨即觸發</li> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/Reference/Events/click" title="/en-US/docs/Web/Reference/Events/click">click</a>：使用者點擊通知之後，隨即觸發</li> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/Reference/Events/close" title="/en-US/docs/Web/Reference/Events/close">close</a>：關閉通知之後，隨即觸發</li> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/Reference/Events/error" title="/en-US/docs/Web/Reference/Events/error">error</a>：通知發生任何錯誤 (大多數是因為某種情況而未顯示通知)，隨即觸發</li> +</ul> + +<p>而透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification.onshow" title="Specifies an event listener to receive show events. These events occur when a Notification is displayed."><code>onshow</code></a>、<a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification.onclick" title="Specifies an event listener to receive click events. These events occur when the user clicks on a displayed Notification."><code>onclick</code></a>、<a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification.onclose" title="Specifies an event listener to receive close events. These events occur when a Notification is closed."><code>onclose</code></a>，或 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification.onerror" title="Specifies an event listener to receive error events. These events occur when something goes wrong with a Notification (in many cases an error prevented the notification from being displayed)."><code>onerror</code></a> 等事件處理器 (Event handler)，即可追蹤這些事件。由於 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification" title="The Notification object is used to configure and display desktop notifications to the user."><code>Notification</code></a> 是繼承 <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget" title="EventTarget is a DOM interface implemented by objects that can receive DOM events and have listeners for them."><code>EventTarget</code></a> 而來，因此亦可使用 <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget.addEventListener" title="addEventListener() registers the specified listener on the EventTarget it's called on. The event target may be an Element in a document, the Document itself, a Window, or any other object that supports events (such as XMLHttpRequest)."><code>addEventListener()</code></a> 函式。</p> + +<div class="note"> +<p><strong>注意：</strong>Firefox 與 Safari 並未遵守 close 事件的規格。此規格雖然規定「僅限使用者能關閉通知」，但 Firefox 與 Safari 卻可於數分鐘後自動關閉通知。因此不一定是由使用者關閉通知。</p> + +<p>此規格並明確規定「應透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Notification.close" title="The close method is used to close a Notification that has been displayed."><code>Notification.close()</code></a> 函式，於應用程式層級完成自動關閉通知」。範例程式碼如下：</p> + +<pre class="brush: js">var n = new Notification("Hi!"); +n.onshow = function () { + setTimeout(n.close, 5000); +} +</pre> +</div> + +<h3 id="簡易範例">簡易範例</h3> + +<p>先假設下列基本 HTML：</p> + +<pre class="brush: html"><button>Notify me!</button></pre> + +<p>則能以這種方法處理通知：</p> + +<pre class="brush: js">window.addEventListener('load', function () { + // At first, let's check if we have permission for notification + // If not, let's ask for it + if (Notification && Notification.permission !== "granted") { + Notification.requestPermission(function (status) { + if (Notification.permission !== status) { + Notification.permission = status; + } + }); + } + var button = document.getElementsByTagName('button')[0]; + button.addEventListener('click', function () { + // If the user agreed to get notified + if (Notification && Notification.permission === "granted") { + var n = new Notification("Hi!"); + } + // If the user hasn't told if he wants to be notified or not + // Note: because of Chrome, we are not sure the permission property + // is set, therefore it's unsafe to check for the "default" value. + else if (Notification && Notification.permission !== "denied") { + Notification.requestPermission(function (status) { + if (Notification.permission !== status) { + Notification.permission = status; + } + // If the user said okay + if (status === "granted") { + var n = new Notification("Hi!"); + } + // Otherwise, we can fallback to a regular modal alert + else { + alert("Hi!"); + } + }); + } + // If the user refuses to get notified + else { + // We can fallback to a regular modal alert + alert("Hi!"); + } + }); +});</pre> + +<h3 id="現場測試結果">現場測試結果</h3> + +<p>若無法顯示，可至本文右上角「Language」切換回英文原文觀看。</p> + +<p>{{ EmbedLiveSample('Simple_example', '100%', 30) }}</p> + +<h2 id="處理多筆通知">處理多筆通知</h2> + +<p>某些情況下 (如某個即時訊息 App 持續通知每一筆進來的訊息)，使用者可能會接收大量的通知。為了避免太多非必要訊息擠爆使用者的桌面，則應該讓等待中的通知進入佇列。</p> + +<p>將標籤添加至任何新的通知，即可達到佇列效果。若通知擁有相同的標籤且尚未顯示，則新通知就會取代先前的通知；反之，若已顯示了相同標籤的通知，就會關閉先前的通知而顯示新通知。</p> + +<h3 id="標籤範例">標籤範例</h3> + +<p>先假設下列基本 HTML：</p> + +<pre class="brush: html"><button>Notify me!</button></pre> + +<p>則能以下列方式處理多筆通知：</p> + +<pre class="brush: js">window.addEventListener('load', function () { + // At first, let's check if we have permission for notification + // If not, let's ask for it + if (Notification && Notification.permission !== "granted") { + Notification.requestPermission(function (status) { + if (Notification.permission !== status) { + Notification.permission = status; + } + }); + } + var button = document.getElementsByTagName('button')[0]; + button.addEventListener('click', function () { + // If the user agreed to get notified + // Let's try to send ten notifications + if (Notification && Notification.permission === "granted") { + for (var i = 0; i < 10; i++) { + // Thanks to the tag, we should only see the "Hi! 10" notification + var n = new Notification("Hi! " + i, {tag: 'soManyNotification'}); + } + } + // If the user hasn't told if he wants to be notified or not + // Note: because of Chrome, we are not sure the permission property + // is set, therefore it's unsafe to check for the "default" value. + else if (Notification && Notification.permission !== "denied") { + Notification.requestPermission(function (status) { + if (Notification.permission !== status) { + Notification.permission = status; + } + // If the user said okay + if (status === "granted") { + for (var i = 0; i < 10; i++) { + // Thanks to the tag, we should only see the "Hi! 10" notification + var n = new Notification("Hi! " + i, {tag: 'soManyNotification'}); + } + } + // Otherwise, we can fallback to a regular modal alert + else { + alert(Hi!"); + } + }); + } + // If the user refuses to get notified + else { + // We can fallback to a regular modal alert + alert(Hi!"); + } + }); +});</pre> + +<h3 id="現場測試結果_2">現場測試結果</h3> + +<p>若無法顯示，可至本文右上角「Language」切換回英文原文觀看。</p> + +<p>{{ EmbedLiveSample('Tag_example', '100%', 30) }}</p> + +<h2 id="規格">規格</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('Web Notifications')}}</td> + <td>{{Spec2('Web Notifications')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{page("/en-US/Web/API/Notification","Browser compatibility")}}</p> + +<h2 id="另可參閱">另可參閱</h2> + +<ul> + <li>{{ domxref("Notification") }}</li> +</ul> diff --git a/files/zh-tw/web/api/parentnode/children/index.html b/files/zh-tw/web/api/parentnode/children/index.html new file mode 100644 index 0000000000..f9f6c76115 --- /dev/null +++ b/files/zh-tw/web/api/parentnode/children/index.html @@ -0,0 +1,152 @@ +--- +title: ParentNode.children +slug: Web/API/ParentNode/children +translation_of: Web/API/ParentNode/children +--- +<p>{{ APIRef("DOM") }}</p> + +<p><code><strong>Node.children</strong></code> 唯讀屬性會回傳一個 <code>Node</code> 之子{{domxref("Element","元素")}}的動態（live）{{domxref("HTMLCollection")}}。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">var <em>children</em> = <em>node</em>.children;</pre> + +<p><code><em>children</em></code> 是一個 {{ domxref("HTMLCollection") }}，為一個有順序性、由 <em><code>node</code></em> 中的 DOM 子元素所組成的集合。假如沒有子元素，則 <code><em>children</em></code> 內便不包含任何元素，且 <code>length</code> 為 <code>0</code>。</p> + +<h2 id="範例">範例</h2> + +<pre class="brush: js">var foo = document.getElementById('foo'); +for (var i = 0; i < foo.children.length; i++) { + console.log(foo.children[i].tagName); +} +</pre> + +<h2 id="Polyfill">Polyfill</h2> + +<pre class="brush: js">// Overwrites native 'children' prototype. +// Adds Document & DocumentFragment support for IE9 & Safari. +// Returns array instead of HTMLCollection. +;(function(constructor) { + if (constructor && + constructor.prototype && + constructor.prototype.children == null) { + Object.defineProperty(constructor.prototype, 'children', { + get: function() { + var i = 0, node, nodes = this.childNodes, children = []; + while (node = nodes[i++]) { + if (node.nodeType === 1) { + children.push(node); + } + } + return children; + } + }); + } +})(window.Node || window.Element); +</pre> + +<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('DOM WHATWG', '#dom-parentnode-children', 'ParentNode.children')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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>Edge</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>Basic support (on {{domxref("Element")}})</td> + <td>1.0</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9.0 [1]</td> + <td>38.0</td> + <td>10.0</td> + <td>4.0</td> + </tr> + <tr> + <td>Support on {{domxref("Document")}} and {{domxref("DocumentFragment")}} {{experimental_inline}}</td> + <td>29.0</td> + <td>{{CompatGeckoDesktop("25.0")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>16.0</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>Support on {{domxref("SVGElement")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</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>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support (on {{domxref("Element")}})</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{CompatGeckoMobile("1.9.1")}}</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatVersionUnknown() }}</td> + </tr> + <tr> + <td>Support on {{domxref("Document")}} and {{domxref("DocumentFragment")}} {{experimental_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("25.0")}}</td> + <td>{{CompatNo}}</td> + <td>16.0</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Internet Explorer 6, 7 and 8 supported it, but erroneously includes {{domxref("Comment")}} nodes.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>The {{domxref("ParentNode")}} and {{domxref("ChildNode")}} interfaces.</li> + <li> + <div class="syntaxbox">Object types implementing this interface: {{domxref("Document")}}, {{domxref("Element")}}, and {{domxref("DocumentFragment")}}.</div> + </li> +</ul> diff --git a/files/zh-tw/web/api/parentnode/firstelementchild/index.html b/files/zh-tw/web/api/parentnode/firstelementchild/index.html new file mode 100644 index 0000000000..4fa9722123 --- /dev/null +++ b/files/zh-tw/web/api/parentnode/firstelementchild/index.html @@ -0,0 +1,95 @@ +--- +title: ParentNode.firstElementChild +slug: Web/API/ParentNode/firstElementChild +translation_of: Web/API/ParentNode/firstElementChild +--- +<p>{{ APIRef("DOM") }}</p> + +<p><strong><code>ParentNode.firstElementChild</code></strong> 介面會會返回 <code>ParentNode</code>的第一個子元素(唯讀) ，如果該節點沒有子節點則返回<code>null</code>。</p> + +<div class="note"> +<p>This property was initially defined in the {{domxref("ElementTraversal")}} pure interface. As this interface contained two distinct set of properties, one aimed at {{domxref("Node")}} that have children, one at those that are children, they have been moved into two separate pure interfaces, {{domxref("ParentNode")}} and {{domxref("ChildNode")}}. In this case, <code>firstElementChild</code> moved to {{domxref("ParentNode")}}. This is a fairly technical change that shouldn't affect compatibility.</p> +</div> + +<h2 id="Syntax_and_values" name="Syntax_and_values">語法</h2> + +<pre class="syntaxbox">var <em>element</em> = node.firstElementChild; +</pre> + +<h2 id="Example" name="Example">範例</h2> + +<pre class="brush: html"><ul id="foo"> + <li>First (1)</li> + <li>Second (2)</li> + <li>Third (3)</li> +</ul> + +<script> +var foo = document.getElementById('foo'); +// yields: First (1) +console.log(foo.firstElementChild.textContent); +</script> +</pre> + +<h2 id="適用於IE8_IE9_和_Safari的Polyfill">適用於IE8, IE9 和 Safari的Polyfill</h2> + +<pre class="brush: js">// Overwrites native 'firstElementChild' prototype. +// Adds Document & DocumentFragment support for IE9 & Safari. +;(function(constructor) { + if (constructor && + constructor.prototype && + constructor.prototype.firstElementChild == null) { + Object.defineProperty(constructor.prototype, 'firstElementChild', { + get: function() { + var node, nodes = this.childNodes, i = 0; + while (node = nodes[i++]) { + if (node.nodeType === 1) { + return node; + } + } + return null; + } + }); + } +})(window.Node || window.Element); +</pre> + +<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('DOM WHATWG', '#dom-parentnode-firstelementchild', 'ParentNode.firstElementChild')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>Split the <code>ElementTraversal</code> interface in {{domxref("ChildNode")}} and <code>ParentNode</code>. This method is now defined on the latter.<br> + The {{domxref("Document")}} and {{domxref("DocumentFragment")}} implemented the new interfaces.</td> + </tr> + <tr> + <td>{{SpecName('Element Traversal', '#attribute-firstElementChild', 'ElementTraversal.firstElementChild')}}</td> + <td>{{Spec2('Element Traversal')}}</td> + <td>Added its initial definition to the <code>ElementTraversal</code> pure interface and use it on {{domxref("Element")}}.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + + + +<p>{{Compat("api.ParentNode.firstElementChild")}}</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("NonDocumentTypeChildNode.nextElementSibling")}}</li> + <li>{{domxref("ParentNode.lastElementChild")}}</li> + <li>The {{domxref("ParentNode")}} and {{domxref("ChildNode")}} pure interfaces.</li> + <li> + <div class="syntaxbox">Object types implementing this pure interface: {{domxref("Document")}}, {{domxref("Element")}}, and {{domxref("DocumentFragment")}}.</div> + </li> +</ul> diff --git a/files/zh-tw/web/api/parentnode/index.html b/files/zh-tw/web/api/parentnode/index.html new file mode 100644 index 0000000000..f3a37abb2f --- /dev/null +++ b/files/zh-tw/web/api/parentnode/index.html @@ -0,0 +1,166 @@ +--- +title: ParentNode +slug: Web/API/ParentNode +translation_of: Web/API/ParentNode +--- +<div>{{APIRef("DOM")}}</div> + +<p><code><strong>ParentNode</strong></code> 介面定義了可以擁有子節點之 {{domxref("Node")}} 物件的方法。</p> + +<p><code>ParentNode</code> 是一個原始的介面，且不能以此建立物件實體。{{domxref("Element")}}、{{domxref("Document")}} 及 {{domxref("DocumentFragment")}} 物件皆實作了 <code>ParentNode</code>。</p> + +<h2 id="屬性">屬性</h2> + +<dl> + <dt>{{domxref("ParentNode.children")}} {{experimental_inline}} {{readonlyInline}}</dt> + <dd>該屬性會返回一個 {{domxref("HTMLCollection")}} 實例，包括 <code>ParentNode</code>的所有子元素節點，需要特別注意的是：該屬性為<code>唯讀</code>。</dd> + <dt>{{domxref("ParentNode.firstElementChild")}} {{experimental_inline}} {{readonlyInline}}</dt> + <dd>該屬性會返回 <code>ParentNode</code>的第一個子元素 ，如果該節點沒有子節點則返回<code>null</code>。</dd> + <dt>{{domxref("ParentNode.lastElementChild")}} {{experimental_inline}} {{readonlyInline}}</dt> + <dd>該屬性會返回 <code>ParentNode</code>的最後一個子元素 ，如果該節點沒有子節點則返回<code>null</code>。</dd> + <dt>{{domxref("ParentNode.childElementCount")}} {{experimental_inline}} {{readonlyInline}}</dt> + <dd>該屬性會返回一個<code>無符號長整數</code> ，該值表示了該節點的子節點數量。</dd> +</dl> + +<h2 id="方法">方法</h2> + +<dl> + <dt>{{domxref("ParentNode.append()")}} {{experimental_inline}}</dt> + <dd>Inserts a set of {{domxref("Node")}} objects or {{domxref("DOMString")}} objects after the last child of the <code>ParentNode</code>. {{domxref("DOMString")}} objects are inserted as equivalent {{domxref("Text")}} nodes.</dd> + <dt>{{domxref("ParentNode.prepend()")}} {{experimental_inline}}</dt> + <dd>Inserts a set of {{domxref("Node")}} objects or {{domxref("DOMString")}} objects before the first child of the <code>ParentNode</code>. {{domxref("DOMString")}} objects are inserted as equivalent {{domxref("Text")}} nodes.</dd> + <dt>{{domxref("ParentNode.querySelector()")}}</dt> + <dd>Returns the first {{domxref("Element")}} with the current element as root that matches the specified group of selectors.</dd> + <dt>{{domxref("ParentNode.querySelectorAll()")}}</dt> + <dd>Returns a {{domxref("NodeList")}} representing a list of elements with the current element as root that matches the specified group of selectors.</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('DOM WHATWG', '#parentnode', 'ParentNode')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>Added the <code>append()</code> and <code>prepend()</code> methods.</td> + </tr> + <tr> + <td>{{SpecName('DOM4', '#parentnode', 'ParentNode')}}</td> + <td>{{Spec2('DOM4')}}</td> + <td>Splitted the <code>ElementTraversal</code> interface in {{domxref("ChildNode")}} and <code>ParentNode</code>. The <code>firstElementChild</code>, <code>lastElementChild</code>, and <code>childElementCount</code> properties are now defined on the latter.<br> + The {{domxref("Document")}} and {{domxref("DocumentFragment")}} implemented the new interfaces.<br> + Added the <code>children</code> property and the <code>querySelector()</code> and <code>querySelectorAll()</code> methods.</td> + </tr> + <tr> + <td>{{SpecName('Element Traversal', '#interface-elementTraversal', 'ElementTraversal')}}</td> + <td>{{Spec2('Element Traversal')}}</td> + <td>Added the initial definition of its properties to the <code>ElementTraversal</code> pure interface and used it on {{domxref("Element")}}.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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 (on {{domxref("Element")}})</td> + <td>{{CompatChrome(1.0)}}</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9.0 [1]</td> + <td>10.0</td> + <td>4.0</td> + </tr> + <tr> + <td>Support on {{domxref("Document")}} and {{domxref("DocumentFragment")}} {{experimental_inline}}</td> + <td>{{CompatChrome(29.0)}}</td> + <td>{{CompatGeckoDesktop(25)}}</td> + <td>{{CompatNo}}</td> + <td>16.0</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>append()</code> and <code>prepend()</code> {{experimental_inline}}</td> + <td>{{CompatChrome(54.0)}}</td> + <td>{{CompatGeckoDesktop(49)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatOpera(39)}}</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>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + <th>Chrome for Mobile</th> + </tr> + <tr> + <td>Basic support (on {{domxref("Element")}})</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("1.9.1")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>Support on {{domxref("Document")}} and {{domxref("DocumentFragment")}} {{experimental_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile(25)}}</td> + <td>{{CompatNo}}</td> + <td>16.0</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>append()</code> and <code>prepend()</code> {{experimental_inline}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatChrome(54.0)}}</td> + <td>{{CompatGeckoMobile(49)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatOperaMobile(39)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatChrome(54.0)}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Internet Explorer 6, 7 and 8 supported it, but erroneously returns {{domxref("Comment")}} nodes as part of the results.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>The {{domxref("ChildNode")}} pure interface.</li> + <li> + <div class="syntaxbox">Object types implementing this pure interface: {{domxref("Document")}}, {{domxref("Element")}}, and {{domxref("DocumentFragment")}}.</div> + </li> +</ul> diff --git a/files/zh-tw/web/api/payment_request_api/index.html b/files/zh-tw/web/api/payment_request_api/index.html new file mode 100644 index 0000000000..d9953e4cfd --- /dev/null +++ b/files/zh-tw/web/api/payment_request_api/index.html @@ -0,0 +1,117 @@ +--- +title: Payment Request API +slug: Web/API/Payment_Request_API +translation_of: Web/API/Payment_Request_API +--- +<div>{{DefaultAPISidebar("Payment Request API")}}{{securecontext_header}}</div> + +<p><span class="seoSummary">Payment Request API 提供商家與用戶雙方一致的用戶體驗。它並不是嶄新的支付方式、而是讓用戶選擇偏好的支付方式、並把該方式提供給商家。</span></p> + +<h2 id="Payment_Request_的概念和用法">Payment Request 的概念和用法</h2> + +<p>很多放棄線上購物的問題，與結帳表單的填寫有關：填寫這些東西既困難又耗時、步驟還極度繁雜。<strong>Payment Request API</strong>正是為減少、甚至擺脫要完成表單所需的填寫步驟而生。它藉由不假手 HTML 表單的情況下，記下要傳給商家的用戶資訊，來簡化結帳步驟。</p> + +<p>針對信用卡付款，使用 Payment Request API 的好處有：</p> + +<ul> + <li><strong>快速的訂購體驗</strong>：用戶在進入瀏覽器時輸入資訊、接著就備齊網路購物所需。用戶再也無須於多個網站，填寫相同資訊。</li> + <li><strong>各站一致且支援 API 的用戶體驗</strong>：由於是瀏覽器在掌管付款資訊，用戶體驗將能客製化、還可以把 UI 本土化為用戶偏好的語言。</li> + <li><strong>無障礙</strong>：由於是瀏覽器在掌管輸入表單，各網站針對鍵盤和螢幕閱讀器的無障礙將確保一致，而無須開發者動工。瀏覽器還能調整輸入表單的字體大小、色彩對比，讓用戶能更輕鬆地完成付款。</li> + <li><strong>憑證管理</strong>：用戶能在瀏覽器，管理信用卡與送達地址的資訊。瀏覽器還能跨設備同步這些「憑證」，以便用戶在電腦與手機周旋間，依舊能輕易付款。</li> + <li><strong>一致的錯誤處理</strong>：瀏覽器會檢查信用卡號碼、並告訴用戶該卡片（將）過期與否；瀏覽器也可以藉由商家的使用模式或限制（例如「只接受 Visa 卡或萬事達卡（Mastercard）」）自動提示用戶、或允許其選擇偏好的信用卡。</li> +</ul> + +<p>要請求支付的話，建立 {{domxref("PaymentRequest")}} 物件的網頁，將回應用戶發動付款的行為，像是點選「購物」按鈕。<code>PaymentRequest</code> 將允許網頁在用戶提供完成交易所需資訊時交換之。</p> + +<p>你可以在 <a href="/zh-TW/docs/Web/API/Payment_Request_API/Using_the_Payment_Request_API">使用 Payment Request API</a> 文章看到完整教學。</p> + +<div class="note"> +<p><strong>注意</strong>：此 API 只有在設定 {{htmlattrxref("allowpaymentrequest","iframe")}} 屬性下，才可支援跨域 {{htmlelement("iframe")}} 元素。</p> +</div> + +<h2 id="介面">介面</h2> + +<dl> + <dt>{{domxref('PaymentAddress')}}</dt> + <dd>地址資訊物件，具體用途有付款與送達。</dd> + <dt>{{domxref('PaymentRequest')}}</dt> + <dd>提供 API 以便建立與管理{{Glossary("用戶代理")}}的付款介面物件。</dd> + <dt>{{domxref('PaymentRequestEvent')}}</dt> + <dd>建立 {{domxref("PaymentRequest")}} 時發送給付款處理器（payment handler）的事件。</dd> + <dt>{{domxref('PaymentRequestUpdateEvent')}}</dt> + <dd>允許網頁針對用戶行為，發動更新用戶付款資訊的請求。</dd> + <dt>{{domxref('PaymentMethodChangeEvent')}}</dt> + <dd>表示用戶更改付款工具（例如從信用卡轉為簽帳金融卡）。</dd> + <dt>{{domxref('PaymentResponse')}}</dt> + <dd>在用戶選取付款方法、並同意付款請求後，所回傳的物件。</dd> + <dt>{{domxref('MerchantValidationEvent')}}</dt> + <dd>表示商家（網站）要求使用特定支付方法的瀏覽器驗證處理器（例如：要不要放行 Apple Pay）</dd> +</dl> + +<h2 id="字詞（dictionary）">字詞（dictionary）</h2> + +<dl> + <dt>{{domxref("AddressErrors")}}</dt> + <dd>此字詞包含任何與 {{domxref("PaymentAddress")}} entry 錯誤相關的描述性解釋字串。</dd> + <dt>{{domxref("PayerErrors")}}</dt> + <dd>此字詞包含任何與 {{domxref("PaymentResponse")}} 的 email、電話、名字屬性（name attribute）錯誤相關之描述性解釋字串。</dd> + <dt>{{domxref("PaymentDetailsUpdate")}}</dt> + <dd>此物件描述伺服器在用戶開始互動前、實例化支付界面後，針對行為需要修改的付款資訊。</dd> +</dl> + + +<h3 id="Related_dictionaries_for_the_Basic_Card_specification">Related dictionaries for the Basic Card specification</h3> + +<dl> + <dt>{{domxref("BasicCardChangeDetails")}}</dt> + <dd>An object providing <em>redacted</em> address information that is provided as the {{domxref("PaymentMethodChangeEvent.methodDetails", "methodDetails")}} on the {{event("paymentmethodchange")}} event sent to the {{domxref("PaymentRequest")}} when the user changes payment information.</dd> + <dt>{{domxref("BasicCardErrors")}}</dt> + <dd>An object providing any error messages associated with the fields in the {{domxref("BasicCardResponse")}} object that are not valid. This is used as the value of the {{domxref("PaymentValidationErrors.paymentMethod", "paymentMethod")}} property on the {{domxref("PaymentValidationErrors")}} object sent to the {{domxref("PaymentRequest")}} when an error occurs.</dd> + <dt>{{domxref('BasicCardRequest')}}</dt> + <dd>Defines an object structure for containing payment request details such as card type.</dd> + <dt>{{domxref('BasicCardResponse')}}</dt> + <dd>Defines an object structure for payment response details such as the number/expiry date of the card used to make the payment, and the billing address.</dd> +</dl> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">註解</th> + </tr> + <tr> + <td>{{SpecName('Payment')}}</td> + <td>{{Spec2('Payment')}}</td> + <td>初始定義。</td> + </tr> + <tr> + <td>{{SpecName('Basic Card Payment')}}</td> + <td>{{Spec2('Basic Card Payment')}}</td> + <td>定義 {{domxref("BasicCardRequest")}} 與 {{domxref("BasicCardResponse")}}，提供處理信用卡付款所需的事務。</td> + </tr> + <tr> + <td>{{SpecName('Payment Method Identifiers')}}</td> + <td>{{Spec2('Payment Method Identifiers')}}</td> + <td>提供付款方法標識、驗證方法、還有 where applicable, minted and formally registered with the W3C。</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<h3 id="PaymentRequest_介面">PaymentRequest 介面</h3> + +<p>{{Compat("api.PaymentRequest", 0)}}</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/zh-TW/docs/Web/API/Payment_Request_API/Using_the_Payment_Request_API">使用 Payment Request API</a></li> + <li><a href="/zh-TW/docs/Web/API/Payment_Request_API/Concepts">Payment 處理概念</a></li> + <li><a href="https://webkit.org/blog/8182/introducing-the-payment-request-api-for-apple-pay/">Introducing the Payment Request API for Apple Pay</a></li> + <li><a href="https://developers.google.com/pay/api/web/guides/paymentrequest/tutorial">Google Pay API PaymentRequest Tutorial</a></li> + <li><a href="https://github.com/w3c/payment-request-info/wiki/FAQ">W3C Payment Request API FAQ</a></li> +</ul> diff --git a/files/zh-tw/web/api/paymentrequest/index.html b/files/zh-tw/web/api/paymentrequest/index.html new file mode 100644 index 0000000000..033ce47312 --- /dev/null +++ b/files/zh-tw/web/api/paymentrequest/index.html @@ -0,0 +1,80 @@ +--- +title: PaymentRequest +slug: Web/API/PaymentRequest +translation_of: Web/API/PaymentRequest +--- +<div>{{securecontext_header}}{{APIRef("Payment Request API")}}</div> + +<p><strong><code>PaymentRequest</code></strong> 介面是 <a href="/zh-TW/docs/Web/API/Payment_Request_API">Payment Request API</a> 的主要切入點，它能讓網頁或 app 接受終端用戶的付款。</p> + +<h2 id="建構子">建構子</h2> + +<dl> + <dt>{{domxref('PaymentRequest.PaymentRequest()','PaymentRequest()')}} {{securecontext_inline}}</dt> + <dd>建立新的 <code>PaymentRequest</code> 物件。</dd> +</dl> + +<h2 id="屬性">屬性</h2> + +<dl> + <dt>{{domxref('PaymentRequest.id')}} {{readonlyinline}}{{securecontext_inline}}</dt> + <dd>個別 <code>PaymentRequest</code> 的唯一標識符（unique identifier），可透過 <code>details.id</code> 設定之。若尚未指定，預設為 UUID。</dd> + <dt>{{domxref('PaymentRequest.shippingAddress')}} {{readonlyinline}} {{securecontext_inline}}</dt> + <dd>若透過付款設定（payment options）請求的話，回傳用戶指定的運送地址，以便計算運輸事宜。只有在呼叫的建構子 <code>requestShipping</code> flag 為 true 時，此屬性才能作動。另外，部份瀏覽器會出於隱私上的理由而只節錄部分地址，除非用戶表示交易手續即將完成（例如按下「付款」鈕）。</dd> + <dt>{{domxref('PaymentRequest.shippingOption')}} {{readonlyinline}} {{securecontext_inline}}</dt> + <dd>回傳的運送選項的標識符。只有在呼叫的建構子 <code>requestShipping</code> flag 為 true 時，此屬性才能作動。</dd> + <dt>{{domxref('PaymentRequest.shippingType')}} {{readonlyinline}} {{securecontext_inline}}</dt> + <dd>回傳用於完成交易的運送類型。可以是 <code>shipping</code>, <code>delivery</code>, <code>pickup</code>, 或在建構子未提供的情形下：<code>null</code>。</dd> +</dl> + +<h3 id="事件處理器">事件處理器</h3> + +<dl> + <dt>{{domxref('PaymentRequest.onshippingaddresschange')}} {{securecontext_inline}}</dt> + <dd>用戶修改運送地址時觸發之。</dd> + <dt>{{domxref('PaymentRequest.onshippingoptionchange')}} {{securecontext_inline}}</dt> + <dd>用戶修改運送選項時觸發之。</dd> + <dt>{{domxref('PaymentRequest.onpaymentmethodchange')}} {{securecontext_inline}}</dt> + <dd>針對付款方法（如 Apple Pay），用戶修改支付方式時觸發之，比方說從信用卡改為簽帳卡。</dd> + <dt>{{domxref('PaymentRequest.onmerchantvalidation')}} {{securecontext_inline}}</dt> + <dd>針對付款方法（如 Apple Pay），本事件會呼叫 {{event("merchantvalidation")}} 事件，在用戶代理要求驗證付款商家或供應商是否合法時觸發之。</dd> +</dl> + +<h2 id="方法">方法</h2> + +<dl> + <dt>{{domxref('PaymentRequest.canMakePayment()')}} {{securecontext_inline}}</dt> + <dd>在呼叫 <code>show()</code> 前告訴 <code>PaymentRequest</code> 物件能不能付款。</dd> +</dl> + +<dl> + <dt>{{domxref('PaymentRequest.show()')}} {{securecontext_inline}}</dt> + <dd>讓用戶代理開始付款請求的用戶交互。</dd> + <dt>{{domxref('PaymentRequest.abort()')}} {{securecontext_inline}}</dt> + <dd>讓用戶代理結束付款請求並刪除可能顯示的任何用戶界面。</dd> +</dl> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">註解</th> + </tr> + <tr> + <td>{{SpecName('Payment','#paymentrequest-interface','PaymentRequest')}}</td> + <td>{{Spec2('Payment')}}</td> + <td>初始定義。</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<div> + + +<p>{{Compat("api.PaymentRequest")}}</p> +</div> diff --git a/files/zh-tw/web/api/performance.timing/index.html b/files/zh-tw/web/api/performance.timing/index.html new file mode 100644 index 0000000000..33d0a54171 --- /dev/null +++ b/files/zh-tw/web/api/performance.timing/index.html @@ -0,0 +1,56 @@ +--- +title: Performance.timing +slug: Web/API/Performance.timing +tags: + - API + - Navigation Timing + - Performance + - Property + - Read-only + - 唯讀 + - 屬性 + - 效能 +translation_of: Web/API/Performance/timing +--- +<p>{{APIRef("Performance")}}</p> + +<h2 id="摘要">摘要</h2> + +<p><code><strong>Performance</strong></code><strong><code>.timing</code></strong> 是唯讀的屬性，傳回的 {{domxref("PerformanceTiming")}} 物件當中包含了效能與時間延遲相關的資訊。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><em>timingInfo</em> = <em>performance</em>.timing;</pre> + +<h2 id="規格">規格</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規格</th> + <th scope="col">狀態</th> + <th scope="col">備註</th> + </tr> + <tr> + <td>{{SpecName('Navigation Timing', '#sec-window.performance-attribute', 'Performance.timing')}}</td> + <td>{{Spec2('Navigation Timing')}}</td> + <td>初步定義</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器支援狀況">瀏覽器支援狀況</h2> + +<div> +<div> + + +<p>{{Compat("api.Performance.timing")}}</p> +</div> +</div> + +<h2 id="參照">參照</h2> + +<ul> + <li>屬於 {{domxref("Performance")}} 界面的一部份</li> +</ul> diff --git a/files/zh-tw/web/api/performance/index.html b/files/zh-tw/web/api/performance/index.html new file mode 100644 index 0000000000..017efb71e1 --- /dev/null +++ b/files/zh-tw/web/api/performance/index.html @@ -0,0 +1,140 @@ +--- +title: Performance +slug: Web/API/Performance +tags: + - API + - Interface + - Navigation Timing + - NeedsTranslation + - Performance + - Reference + - TopicStub + - Web Performance +translation_of: Web/API/Performance +--- +<div>{{APIRef("High Resolution Time")}}</div> + +<p>The <strong><code>Performance</code></strong> interface provides access to performance-related information for the current page. It's part of the High Resolution Time API, but is enhanced by the <a href="/en-US/docs/Web/API/Performance_Timeline">Performance Timeline API</a>, the <a href="/en-US/docs/Web/API/Navigation_timing_API">Navigation Timing API</a>, the <a href="/en-US/docs/Web/API/User_Timing_API">User Timing API</a>, and the <a href="/en-US/docs/Web/API/Resource_Timing_API">Resource Timing API</a>.</p> + +<p>An object of this type can be obtained by calling the {{domxref("Window.performance")}} read-only attribute.</p> + +<div class="note"> +<p><strong><em>Note</em>: </strong>This interface and its members are available in <a href="/en-US/docs/Web/API/Web_Workers_API">Web Workers</a>, except where indicated below. Also note that performance markers and measures are per context. If you create a mark on the main thread (or other worker), you cannot see it in a worker thread, and vice versa.</p> +</div> + +<h2 id="Properties">Properties</h2> + +<p><em>The <code>Performance</code> interface doesn't inherit any properties.</em></p> + +<dl> + <dt>{{deprecated_inline}} {{domxref("Performance.navigation")}} {{readonlyInline}}</dt> + <dd>A {{domxref("PerformanceNavigation")}} object that provides useful context about the operations included in the times listed in <code>timing</code>, including whether the page was a load or a refresh, how many redirections occurred, and so forth.</dd> + <dt>{{deprecated_inline}} {{domxref("Performance.timing")}} {{readonlyInline}}</dt> + <dd>A {{domxref("PerformanceTiming")}} object containing latency-related performance information. Not available in workers.</dd> + <dt>{{domxref("Performance.memory", "performance.memory")}} {{Non-standard_inline}}</dt> + <dd>A <em>non-standard</em> extension added in Chrome, this property provides an object with basic memory usage information. <em>You <strong>should not use</strong> this non-standard API.</em></dd> + <dt>{{domxref("Performance.timeOrigin")}} {{readonlyInline}} {{Non-standard_inline}}</dt> + <dd>Returns the high resolution timestamp of the start time of the performance measurement.</dd> +</dl> + +<dl> + <dt> + <h3 id="Event_handlers">Event handlers</h3> + </dt> + <dt>{{domxref("Performance.onresourcetimingbufferfull")}}</dt> + <dd>An {{domxref("EventTarget")}} which is a callback that will be called when the {{event("resourcetimingbufferfull")}} event is fired.</dd> +</dl> + +<h2 id="Methods">Methods</h2> + +<p><em><em>The <code>Performance</code> interface doesn't inherit any </em>methods</em>.</p> + +<dl> + <dt>{{domxref("Performance.clearMarks()")}}</dt> + <dd>Removes the given <em>mark</em> from the browser's performance entry buffer.</dd> + <dt>{{domxref("Performance.clearMeasures()")}}</dt> + <dd>Removes the given <em>measure</em> from the browser's performance entry buffer.</dd> + <dt>{{domxref("Performance.clearResourceTimings()")}}</dt> + <dd>Removes all {{domxref("PerformanceEntry","performance entries")}} with a {{domxref("PerformanceEntry.entryType","entryType")}} of "<code>resource</code>" from the browser's performance data buffer.</dd> + <dt>{{domxref("Performance.getEntries()")}}</dt> + <dd>Returns a list of {{domxref("PerformanceEntry")}} objects based on the given <em>filter</em>.</dd> + <dt>{{domxref("Performance.getEntriesByName()")}}</dt> + <dd>Returns a list of {{domxref("PerformanceEntry")}} objects based on the given <em>name</em> and <em>entry type</em>.</dd> + <dt>{{domxref("Performance.getEntriesByType()")}}</dt> + <dd>Returns a list of {{domxref("PerformanceEntry")}} objects of the given <em>entry type</em>.</dd> + <dt>{{domxref("Performance.mark()")}}</dt> + <dd>Creates a {{domxref("DOMHighResTimeStamp","timestamp")}} in the browser's <em>performance entry buffer</em> with the given name.</dd> + <dt>{{domxref("Performance.measure()")}}</dt> + <dd>Creates a named {{domxref("DOMHighResTimeStamp","timestamp")}} in the browser's performance entry buffer between two specified marks (known as the <em>start mark</em> and <em>end mark</em>, respectively).</dd> + <dt>{{domxref("Performance.now()")}}</dt> + <dd>Returns a {{domxref("DOMHighResTimeStamp")}} representing the number of milliseconds elapsed since a reference instant.</dd> + <dt>{{domxref("Performance.setResourceTimingBufferSize()")}}</dt> + <dd>Sets the browser's resource timing buffer size to the specified number of "<code>resource</code>" {{domxref("PerformanceEntry.entryType","type")}} {{domxref("PerformanceEntry","performance entry")}} objects.</dd> + <dt>{{domxref("Performance.toJSON()")}}</dt> + <dd>Is a jsonizer returning a json object representing the <code>Performance</code> object.</dd> +</dl> + +<h2 id="Specifications">Specifications</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('Highres Time Level 3', '#dom-performance-timeorigin','timeOrigin')}}</td> + <td>{{Spec2('Highres Time Level 3')}}</td> + <td>Defines <code>timeOrigin</code> property.</td> + </tr> + <tr> + <td>{{SpecName('Highres Time Level 2', '#the-performance-interface', 'toJSON()')}}</td> + <td>{{Spec2('Highres Time Level 2')}}</td> + <td>Defines <code>toJson()</code> method.</td> + </tr> + <tr> + <td>{{SpecName('Highres Time', '#the-performance-interface', 'Performance')}}</td> + <td>{{Spec2('Highres Time')}}</td> + <td>Defines <code>now()</code> method.</td> + </tr> + <tr> + <td>{{SpecName('Navigation Timing', '#sec-window.performance-attribute', 'Performance')}}</td> + <td>{{Spec2('Navigation Timing')}}</td> + <td>Defines <code>timing</code> and <code>navigation</code> properties.</td> + </tr> + <tr> + <td>{{SpecName('Performance Timeline Level 2', '#extensions-to-the-performance-interface', 'Performance extensions')}}</td> + <td>{{Spec2('Performance Timeline Level 2')}}</td> + <td>Changes <code>getEntries()</code> interface.</td> + </tr> + <tr> + <td>{{SpecName('Performance Timeline', '#sec-window.performance-attribute', 'Performance extensions')}}</td> + <td>{{Spec2('Performance Timeline')}}</td> + <td>Defines <code>getEntries()</code>, <code>getEntriesByType()</code> and <code>getEntriesByName()</code> methods.</td> + </tr> + <tr> + <td>{{SpecName('Resource Timing', '#extensions-performance-interface', 'Performance extensions')}}</td> + <td>{{Spec2('Resource Timing')}}</td> + <td>Defines <code>clearResourceTimings()</code> and <code>setResourceTimingBufferSize()</code> methods and the <code>onresourcetimingbufferfull</code> property.</td> + </tr> + <tr> + <td>{{SpecName('User Timing Level 2', '#extensions-performance-interface', 'Performance extensions')}}</td> + <td>{{Spec2('User Timing Level 2')}}</td> + <td>Clarifies <code>mark()</code>, <code>clearMark()</code>, <code>measure()</code> and <code>clearMeasure()</code> methods.</td> + </tr> + <tr> + <td>{{SpecName('User Timing', '#extensions-performance-interface', 'Performance extensions')}}</td> + <td>{{Spec2('User Timing')}}</td> + <td>Defines <code>mark()</code>, <code>clearMark()</code>, <code>measure()</code> and <code>clearMeasure()</code> methods.</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<div> + + +<p>{{Compat("api.Performance")}}</p> +</div> diff --git a/files/zh-tw/web/api/pointer_lock_api/index.html b/files/zh-tw/web/api/pointer_lock_api/index.html new file mode 100644 index 0000000000..e37e5ceea5 --- /dev/null +++ b/files/zh-tw/web/api/pointer_lock_api/index.html @@ -0,0 +1,285 @@ +--- +title: Pointer Lock API +slug: Web/API/Pointer_Lock_API +translation_of: Web/API/Pointer_Lock_API +--- +<p>{{ SeeCompatTable() }}</p> + +<p><strong>Pointer lock</strong> (之前稱為 Mouse lock) 提供「隨時間經過所產生的滑鼠位移資訊 (即 deltas)」的輸入方法，而不只是滑鼠游標的絕對位置而已。此函式可存取基本的滑鼠位移、將滑鼠事件的目標鎖定至單一元素、讓滑鼠單一方向的位移距離不再受限、將游標移除到視點之外。</p> + +<p>若 App 需要大量的滑鼠輸入以控制位移、旋轉物件、更改輸入項，那此 API 就特別有用。另對特別注重視覺效果的 App 尤其必要，如第一人稱視角、3D 視圖、模型建構等。</p> + +<p>舉例來說，你可讓消費者不需點擊任何按鈕，只要透過滑鼠即可控制視角。而按鈕可用於其他動作。對於查看地圖、衛星圖像、第一人稱場景類 (如遊戲或虛擬實境影片) 的 App 來說，這種滑鼠輸入方式特別方便易用。</p> + +<p>即使滑鼠游標移出瀏覽器或螢幕之外，Pointer lock 還是能讓你存取滑鼠事件。舉例來說，消費者還是可繼續移動滑鼠以旋轉或操作 3D 模型。若沒有 Pointer lock，則只要指標移出瀏覽器或螢幕之外，旋轉或操作隨即停止。遊戲玩家會特別喜歡此功能。他們現在可以隨便亂按按鈕並隨意滑動滑鼠；不再擔心滑鼠游標滑出遊戲區域而點到其他應用程式，結果退出遊戲發生慘案！</p> + +<h2 id="basics" name="basics">基本概念</h2> + +<p>Pointer lock 與 <a href="/en/DOM/element.setCapture" title="element.setCapture">mouse capture </a>相關。在拖曳滑鼠時，Mouse capture 可持續向目標元素傳遞事件，且只要放開滑鼠按鈕隨即跟著停止。Pointer lock 與 mouse capture 不同之處在於：</p> + +<ul> + <li>Pointer lock 屬持久性。除非發生顯式 (Explicit) API 呼叫，或使用者做出特定的釋放手勢，否則 Pointer lock 將不會釋放滑鼠。</li> + <li>Pointer lock 不侷限於螢幕或瀏覽器的範圍。</li> + <li>不論滑鼠按鈕狀態為何，Pointer lock 將持續送出事件。</li> + <li>Pointer lock 會隱藏游標。</li> +</ul> + +<h2 id="example" name="example">範例</h2> + +<p>下列範例可讓你設定自己網頁上的 Pointer lock。</p> + +<pre class="brush: js"><button onclick="lockPointer();">Lock it!</button> +<div id="pointer-lock-element"></div> +<script> +// Note: at the time of writing, only Mozilla and WebKit support Pointer Lock. + +// The element we'll make fullscreen and pointer locked. +var elem; + +document.addEventListener("mousemove", function(e) { + var movementX = e.movementX || + e.mozMovementX || + e.webkitMovementX || + 0, + movementY = e.movementY || + e.mozMovementY || + e.webkitMovementY || + 0; + + // Print the mouse movement delta values + console.log("movementX=" + movementX, "movementY=" + movementY); +}, false); + +function fullscreenChange() { + if (document.webkitFullscreenElement === elem || + document.mozFullscreenElement === elem || + document.mozFullScreenElement === elem) { // Older API upper case 'S'. + // Element is fullscreen, now we can request pointer lock + elem.requestPointerLock = elem.requestPointerLock || + elem.mozRequestPointerLock || + elem.webkitRequestPointerLock; + elem.requestPointerLock(); + } +} + +document.addEventListener('fullscreenchange', fullscreenChange, false); +document.addEventListener('mozfullscreenchange', fullscreenChange, false); +document.addEventListener('webkitfullscreenchange', fullscreenChange, false); + +function pointerLockChange() { + if (document.mozPointerLockElement === elem || + document.webkitPointerLockElement === elem) { + console.log("Pointer Lock was successful."); + } else { + console.log("Pointer Lock was lost."); + } +} + +document.addEventListener('pointerlockchange', pointerLockChange, false); +document.addEventListener('mozpointerlockchange', pointerLockChange, false); +document.addEventListener('webkitpointerlockchange', pointerLockChange, false); + +function pointerLockError() { + console.log("Error while locking pointer."); +} + +document.addEventListener('pointerlockerror', pointerLockError, false); +document.addEventListener('mozpointerlockerror', pointerLockError, false); +document.addEventListener('webkitpointerlockerror', pointerLockError, false); + +function lockPointer() { + elem = document.getElementById("pointer-lock-element"); + // Start by going fullscreen with the element. Current implementations + // require the element to be in fullscreen before requesting pointer + // lock--something that will likely change in the future. + elem.requestFullscreen = elem.requestFullscreen || + elem.mozRequestFullscreen || + elem.mozRequestFullScreen || // Older API upper case 'S'. + elem.webkitRequestFullscreen; + elem.requestFullscreen(); +} +</script> +</pre> + +<h2 id="method_overview" name="method_overview"><strong>函式/屬性概述</strong></h2> + +<p>Pointer lock API 與 Fullscreen API 類似，可添增 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Element.requestPointerLock" title="The requestPointerLock allows to asynchronously ask for the pointer to be locked on the given element.">requestPointerLock</a> 新函式 (目前尚未標準化) 而擴充 DOM 元素。可為下列：</p> + +<pre class="brush: js">element.webkitRequestPointerLock(); // Chrome +element.mozRequestPointerLock(); // Firefox +element.requestPointerLock(); // Standard</pre> + +<p>目前在建置 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Element.requestPointerLock" title="The requestPointerLock allows to asynchronously ask for the pointer to be locked on the given element.">requestPointerLock</a> 時，還是必須緊密結合 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Element.requestFullScreen" title="Asynchronously requests that the element be made full-screen.">requestFullScreen</a> 與 Fullscreen API。在指標鎖定某一元素之前，必須先進入全螢幕模式。如同上方的 Demo，指標鎖定屬於非同步程序，並透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers.pointerlockchange" title="/en-US/docs/Web/API/GlobalEventHandlers.pointerlockchange">pointerlockchange</a> 與 <a href="https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers.pointerlockerror" title="/en-US/docs/Web/API/GlobalEventHandlers.pointerlockerror">pointerlockerror</a> 事件，指出該請求是否成功。此與 Fullscreen API 的運作方式相同 (使用其 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Element.requestFullScreen" title="Asynchronously requests that the element be made full-screen.">requestFullScreen</a> 函式，另搭配 <a href="https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers.fullscreenchange" title="/en-US/docs/Web/API/GlobalEventHandlers.fullscreenchange">fullscreenchange</a> 與 <a href="https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers.fullscreenerror" title="/en-US/docs/Web/API/GlobalEventHandlers.fullscreenerror">fullscreenerror</a> 事件)。</p> + +<p>Pointer lock API 另擴充了 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Document" title="Each web page loaded in the browser has its own document object. The Document interface serves as an entry point to the web page's content (the DOM tree, including elements such as <body> and <table>) and provides functionality global to the document (suc">Document</a> 介面，同時添增了新的屬性與函式。如果目前有鎖定的元素，則新的屬性可存取該所訂元素，並命名為 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Document.pointerLockElement" title="The pointerLockElement property provides the element set as the target for mouse events while the pointer is locked. It is null if lock is pending, pointer is unlocked, or the target is in another document.">pointerLockElement</a> (目前尚未標準化)。<a href="https://developer.mozilla.org/en-US/docs/Web/API/Document" title="Each web page loaded in the browser has its own document object. The Document interface serves as an entry point to the web page's content (the DOM tree, including elements such as <body> and <table>) and provides functionality global to the document (suc">Document</a> 上的新函式則為 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Document.exitPointerLock" title="The exitPointerLock asynchronously releases a pointer lock previously requested through Element.requestPointerLock.">exitPointerLock</a>；顧名思義，此函式可退出 Pointer lock。</p> + +<p><a href="https://developer.mozilla.org/en-US/docs/Web/API/Document.pointerLockElement" title="The pointerLockElement property provides the element set as the target for mouse events while the pointer is locked. It is null if lock is pending, pointer is unlocked, or the target is in another document.">pointerLockElement</a> 屬性可確定指標目前是否鎖定了任何元素 (例如進行 Boolean 檢查)。若確實有鎖定的元素，則可取得參考。以下為此二種用法的範例：</p> + +<pre class="brush: js"><span class="idlInterface" id="idl-def-MouseLockable"><span class="idlInterface" id="idl-def-MouseLockable">document.pointerLockElement = document.pointerLockElement || + document.mozPointerLockElement || + document.webkitPointerLockElement;</span></span> + +// 1) Used as a boolean check: are we pointer locked? +if (!!document.pointerLockElement) { + // pointer is locked +} else { + // pointer is not locked +} + +// 2) Used to access the pointer locked element +if (document.pointerLockElement === someElement) { + // someElement is currently pointer locked +} +</pre> + +<p><a href="https://developer.mozilla.org/en-US/docs/Web/API/Document.exitPointerLock" title="The exitPointerLock asynchronously releases a pointer lock previously requested through Element.requestPointerLock.">Document.exitPointerLock</a> 函式則用以退出 Pointer lock。且和 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Element.requestPointerLock" title="The requestPointerLock allows to asynchronously ask for the pointer to be locked on the given element.">requestPointerLock</a> 一樣，<a href="https://developer.mozilla.org/en-US/docs/Web/API/Document.exitPointerLock" title="The exitPointerLock asynchronously releases a pointer lock previously requested through Element.requestPointerLock.">Document.exitPointerLock</a> 是使用 <a href="https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers.pointerlockchange" title="/en-US/docs/Web/API/GlobalEventHandlers.pointerlockchange">pointerlockchange</a> 與 <a href="https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers.pointerlockerror" title="/en-US/docs/Web/API/GlobalEventHandlers.pointerlockerror">pointerlockerror</a> 事件，以非同步方式作業：</p> + +<pre class="brush: js">document.exitPointerLock = document.exitPointerLock || + document.mozExitPointerLock || + document.webkitExitPointerLock; + +function pointerLockChange() { + document.pointerLockElement = document.pointerLockElement || + document.mozPointerLockElement || + document.webkitPointerLockElement; + + if (!!document.pointerLockElement) { + console.log("Still locked."); + } else { + console.log("Exited lock."); + } +} + +document.addEventListener('pointerlockchange', pointerLockChange, false); +document.addEventListener('mozpointerlockchange', pointerLockChange, false); +document.addEventListener('webkitpointerlockchange', pointerLockChange, false); + +// Attempt to unlock +document.exitPointerLock(); +</pre> + +<h2 id="mouselocklostevent" name="mouselocklostevent">pointerlockchange 事件</h2> + +<p>若 Pointer lock 狀態改變，如呼叫 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Element.requestPointerLock" title="The requestPointerLock allows to asynchronously ask for the pointer to be locked on the given element.">requestPointerLock</a>、<a href="https://developer.mozilla.org/en-US/docs/Web/API/Document.exitPointerLock" title="The exitPointerLock asynchronously releases a pointer lock previously requested through Element.requestPointerLock.">exitPointerLock</a>，或使用者按下 ESC 鍵等。則 <a href="https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers.pointerlockchange" title="/en-US/docs/Web/API/GlobalEventHandlers.pointerlockchange">pointerlockchange</a> 事件隨即傳送至 <code>document</code>。此簡單事件不包含額外資料。</p> + +<div class="note">此事件目前在 Firefox 中的前綴為 <code>mozpointerlockchange</code>；在 Chrome 中的前綴為 <code>webkitpointerlockchange</code>。</div> + +<h2 id="mouselocklostevent" name="mouselocklostevent">pointerlockerror 事件</h2> + +<p>當呼叫 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Element.requestPointerLock" title="The requestPointerLock allows to asynchronously ask for the pointer to be locked on the given element.">requestPointerLock</a> 或 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Document.exitPointerLock" title="The exitPointerLock asynchronously releases a pointer lock previously requested through Element.requestPointerLock.">exitPointerLock</a> 而發生錯誤時，隨即傳送 <a href="https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers.pointerlockerror" title="/en-US/docs/Web/API/GlobalEventHandlers.pointerlockerror">pointerlockerror</a> 事件至 <code>document</code>。此簡單事件不包含額外資料。</p> + +<div class="note">此事件在 Firefox 中的前綴為 <code>mozpointerlockerror</code>；在 Chrome 中的前綴為 <code>webkitpointerlockerror</code>。</div> + +<h2 id="extensions" name="extensions">擴充至滑鼠事件</h2> + +<p>Pointer lock API 可透過位移屬性而擴充標準的 <a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent" title="The DOM MouseEvent interface represents events that occur due to the user interacting with a pointing device (such as a mouse).">MouseEvent</a> 介面。</p> + +<pre class="idl"><span class="idlInterface" id="idl-def-MouseEvent">partial interface <span class="idlInterfaceID">MouseEvent</span> { +<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>long</a></span> <span class="idlAttrName"><a href="http://dvcs.w3.org/hg/webevents/raw-file/default/mouse-lock.html#widl-MouseEvent-movementX">movementX</a></span>;</span> +<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>long</a></span> <span class="idlAttrName"><a href="http://dvcs.w3.org/hg/webevents/raw-file/default/mouse-lock.html#widl-MouseEvent-movementY">movementY</a></span>;</span> +};</span></pre> + +<div class="note">位移屬性目前在 Firefox 中的前綴為 <code>.mozMovementX</code> 與 <code>.mozMovementY</code>；在 Chrome 中的前綴為<code>.webkitMovementX</code> 與 <code>.webkitMovementY</code>。</div> + +<p>滑鼠事件的二個新參數 (即 <a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent.movementX" title="The movementX property provides the shift in the X coordinate of the mouse pointer between that event and the previous mousemove event. In other words, the value of that property is computed that way : currentEvent.movementX = currentEvent.screenX - previ">movementX</a> 與 <a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent.movementY" title="The movementY property provides the shift in the Y coordinate of the mouse pointer between that event and the previous mousemove event. In other words, the value of that property is computed that way : currentEvent.movementY = currentEvent.screenY - previ">movementY</a>) 將提供滑鼠位置的變化情形。此二項參數的值，等於 <a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent" title="The DOM MouseEvent interface represents events that occur due to the user interacting with a pointing device (such as a mouse).">MouseEvent</a> 屬性值 (即 <a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent.screenX" title="The screenX property provides the X coordinate of the mouse pointer in global (screen) coordinates.">screenX</a> 與 <a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent.screenY" title="The screenY property provides the Y coordinate of the mouse pointer in global (screen) coordinates.">screenY</a>) 之間的變化；而 <a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent" title="The DOM MouseEvent interface represents events that occur due to the user interacting with a pointing device (such as a mouse).">MouseEvent</a> 屬性另儲存於二項連續的 <a href="https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers.mousemove" title="/en-US/docs/Web/API/GlobalEventHandlers.mousemove">mousemove</a> 事件 (即 eNow 與 ePrevious) 之內。換句話說，Pointer lock 參數 <code>movementX = eNow.screenX - ePrevious.screenX</code>。</p> + +<h3 id="locked_state" name="locked_state">鎖定狀態</h3> + +<p>在啟動 Pointer lock 之後，標準的 <a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent" title="The DOM MouseEvent interface represents events that occur due to the user interacting with a pointing device (such as a mouse).">MouseEvent</a> 屬性 <a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent.clientX" title="Editorial review completed.">clientX</a>、<a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent.clientY" title="The clientY property provides the Y coordinate of the mouse pointer in local (DOM content) coordinates.">clientY</a>、<a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent.screenX" title="The screenX property provides the X coordinate of the mouse pointer in global (screen) coordinates.">screenX</a>、<a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent.screenY" title="The screenY property provides the Y coordinate of the mouse pointer in global (screen) coordinates.">screenY</a> 均維持不變，如同滑鼠沒有移動。<a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent.movementX" title="The movementX property provides the shift in the X coordinate of the mouse pointer between that event and the previous mousemove event. In other words, the value of that property is computed that way : currentEvent.movementX = currentEvent.screenX - previ">movementX</a> 與 <a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent.movementY" title="The movementY property provides the shift in the Y coordinate of the mouse pointer between that event and the previous mousemove event. In other words, the value of that property is computed that way : currentEvent.movementY = currentEvent.screenY - previ">movementY</a> 屬性將持續提供滑鼠的位置變化。如果滑鼠朝單一方向持續移動，<a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent.movementX" title="The movementX property provides the shift in the X coordinate of the mouse pointer between that event and the previous mousemove event. In other words, the value of that property is computed that way : currentEvent.movementX = currentEvent.screenX - previ">movementX</a> 與 <a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent.movementY" title="The movementY property provides the shift in the Y coordinate of the mouse pointer between that event and the previous mousemove event. In other words, the value of that property is computed that way : currentEvent.movementY = currentEvent.screenY - previ">movementY</a> 的值也就不受限。此時「滑鼠游標」的概念不存在，游標無法移出視窗之外，也不會受限於螢幕邊界。</p> + +<h3 id="unlocked_state" name="unlocked_state"><strong>未鎖定狀態</strong></h3> + +<p>無論滑鼠的鎖定狀態為何，<a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent.movementX" title="The movementX property provides the shift in the X coordinate of the mouse pointer between that event and the previous mousemove event. In other words, the value of that property is computed that way : currentEvent.movementX = currentEvent.screenX - previ">movementX</a> 與 <a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent.movementY" title="The movementY property provides the shift in the Y coordinate of the mouse pointer between that event and the previous mousemove event. In other words, the value of that property is computed that way : currentEvent.movementY = currentEvent.screenY - previ">movementY</a> 參數均保持有效；另為了方便起見，甚至在未鎖定狀態下仍可保持有效。</p> + +<p>在解鎖滑鼠之後，系統游標可退出並重新進入瀏覽器視窗，且 <a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent.movementX" title="The movementX property provides the shift in the X coordinate of the mouse pointer between that event and the previous mousemove event. In other words, the value of that property is computed that way : currentEvent.movementX = currentEvent.screenX - previ">movementX</a> 與 <a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent.movementY" title="The movementY property provides the shift in the Y coordinate of the mouse pointer between that event and the previous mousemove event. In other words, the value of that property is computed that way : currentEvent.movementY = currentEvent.screenY - previ">movementY</a> 此時可能設定為零。</p> + +<h2 id="iframe_限制">iframe 限制</h2> + +<p>Pointer lock 一次僅能鎖定一組 iframe。在鎖定一組 iframe 之後，就無法鎖定另一組 iframe 並轉移目標至該 iframe 之上；Pointer lock 將發生錯誤。為擺脫此限制，必須先將鎖定的 iframe 解鎖，再鎖定另一組 iframe。</p> + +<p>由於 iframes 是根據預設值運作，因此預設為「沙箱式 (sandboxed)」的 iframes 將阻擋 Pointer lock。為擺脫此限制，Chrome 應該很快就會推出 <code><iframe sandbox="allow-pointer-lock"></code> 的「屬性/值」整合形式。</p> + +<h2 id="規格">規格</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('Pointer Lock')}}</td> + <td>{{Spec2('Pointer Lock')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility" name="Browser_compatibility">瀏覽器相容性</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td> + <p>Targeting 23{{ property_prefix("webkit") }}*</p> + + <p>See <a class="external" href="http://code.google.com/p/chromium/issues/detail?id=72754" title="http://code.google.com/p/chromium/issues/detail?id=72754">CR/72574</a></p> + </td> + <td> + <p>{{ CompatGeckoDesktop("14.0") }}</p> + + <p>{{bug("633602") }}</p> + </td> + <td>{{ CompatNo() }}</td> + <td>{{ CompatNo() }}</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>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{ CompatNo() }}</td> + <td>{{ CompatNo() }}</td> + <td>{{ CompatNo() }}</td> + <td>{{ CompatNo() }}</td> + <td>{{ CompatNo() }}</td> + </tr> + </tbody> +</table> +</div> + +<p>* 需啟動 <code>about:flags</code> 中的功能；或以 <code>--enable-pointer-lock</code> 旗標啟動 Chrome。</p> + +<h2 id="See_also" name="See_also">另可參閱</h2> + +<ul> + <li>{{domxref("MouseEvent")}}</li> +</ul> diff --git a/files/zh-tw/web/api/positionoptions/enablehighaccuracy/index.html b/files/zh-tw/web/api/positionoptions/enablehighaccuracy/index.html new file mode 100644 index 0000000000..8437f37fe6 --- /dev/null +++ b/files/zh-tw/web/api/positionoptions/enablehighaccuracy/index.html @@ -0,0 +1,93 @@ +--- +title: PositionOptions.enableHighAccuracy +slug: Web/API/PositionOptions/enableHighAccuracy +translation_of: Web/API/PositionOptions/enableHighAccuracy +--- +<div>{{APIRef("Geolocation API")}}</div> + +<p><code><strong>PositionOptions.enableHighAccuracy</strong></code> 是一個 {{domxref("Boolean")}} 的值。此值指出方法是否需要回傳最佳的結果。如果值為真且該裝置是具備提供精準位置的能力，則方法會回傳最佳結果。必須注意的是最佳結果會導致較長的回應時間或者需要更多的電力耗損 (舉例來說擁有GPS晶片的手機)。相反來說，如果值為偽，<code>機器會因為回應時間較短以及消耗較少的電力達到資源節省</code>。預設值：偽。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><var>positionOptions</var>.enableHighAccuracy = <var>booleanValue</var> +</pre> + +<h2 id="規格">規格</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('Geolocation', '#enablehighaccuracy', 'PositionOptions.enableHighAccuracy')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + {{CompatNo}} 15.0<br> + 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown}}</td> + <td>10.60</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>屬於{{domxref("PositionOptions")}} 。</li> +</ul> diff --git a/files/zh-tw/web/api/positionoptions/index.html b/files/zh-tw/web/api/positionoptions/index.html new file mode 100644 index 0000000000..fc27485e65 --- /dev/null +++ b/files/zh-tw/web/api/positionoptions/index.html @@ -0,0 +1,105 @@ +--- +title: PositionOptions +slug: Web/API/PositionOptions +translation_of: Web/API/PositionOptions +--- +<div>{{APIRef("Geolocation API")}}</div> + +<p><strong><code>PositionOptions</code></strong> 是一個當作 {{domxref("Geolocation.getCurrentPosition()")}} 以及 {{domxref("Geolocation.watchPosition()")}} 參數的物件，此物件含有幾種可以設定的屬性。</p> + +<h2 id="屬性">屬性</h2> + +<p><em><code>PositionOptions</code> </em>介面沒有繼承任何屬性</p> + +<dl> + <dt>{{domxref("PositionOptions.enableHighAccuracy")}}</dt> + <dd>是一個 {{domxref("Boolean")}} 的值。此值指出方法是否需要回傳最佳的結果。如果值為真且該裝置具備提供精準位置的能力，則方法會回傳最佳結果。必須注意的是最佳結果會導致較長的回應時間或者需要更多的電力耗損 (舉例來說擁有GPS晶片的手機)。相反來說，如果值為偽，<code>機器會因為回應時間較短以及消耗較少的電力達到資源節省</code>。預設值：偽。</dd> + <dt>{{domxref("PositionOptions.timeout")}}</dt> + <dd>這是一個正值，它代表機器能夠等待方法回傳位置的最長時間（單位是毫秒）。預設值是 <code><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Infinity">Infinity</a></code>，代表 <code>getCurrentPosition()</code> 此方法在沒有可用的位置前不會有任何回覆。</dd> + <dt>{{domxref("PositionOptions.maximumAge")}}</dt> + <dd>這是一個正值，它代表可以接受暫存位置的最長時限（單位是毫秒）。如果設定為 0，代表機器必須回傳實際的當前位置而不能使用暫存位置。如果設定為 <code><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Infinity">Infinity</a></code>，機器必定會回傳暫存位置而不考慮他的時限。預設值：0。</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><code>PositionOptions</code> 介面沒有實現也沒有繼承任何方法。</p> + +<h2 id="規格">規格</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('Geolocation', '#positionoptions', 'PositionOptions')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + {{CompatNo}} 15.0<br> + 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown}}</td> + <td>10.60</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>{{domxref("Geolocation")}} 介面使用此物件。</li> +</ul> diff --git a/files/zh-tw/web/api/positionoptions/maximumage/index.html b/files/zh-tw/web/api/positionoptions/maximumage/index.html new file mode 100644 index 0000000000..2f9d1cf48e --- /dev/null +++ b/files/zh-tw/web/api/positionoptions/maximumage/index.html @@ -0,0 +1,93 @@ +--- +title: PositionOptions.maximumAge +slug: Web/API/PositionOptions/maximumAge +translation_of: Web/API/PositionOptions/maximumAge +--- +<div>{{APIRef("Geolocation API")}}</div> + +<p><code><strong>PositionOptions.maximumAge</strong></code> 是一個正值，它代表可以接受暫存位置的最長期限（單位是毫秒）。如果設定為 0，代表機器必須回傳實際的當前位置而不能使用暫存位置。如果設定為 <code><a href="https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Infinity">Infinity</a></code>， 機器必定會回傳暫存位置而不考慮他的期限。預設值：0。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><var>positionOptions</var>.maximumAge = <var>timeLength</var> +</pre> + +<h2 id="規格">規格</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('Geolocation', '#maximumage', 'PositionOptions.maximumAge')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + {{CompatNo}} 15.0<br> + 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown}}</td> + <td>10.60</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>屬於 {{domxref("PositionOptions")}} 。</li> +</ul> diff --git a/files/zh-tw/web/api/positionoptions/timeout/index.html b/files/zh-tw/web/api/positionoptions/timeout/index.html new file mode 100644 index 0000000000..f963a28764 --- /dev/null +++ b/files/zh-tw/web/api/positionoptions/timeout/index.html @@ -0,0 +1,93 @@ +--- +title: PositionOptions.timeout +slug: Web/API/PositionOptions/timeout +translation_of: Web/API/PositionOptions/timeout +--- +<div>{{APIRef("Geolocation API")}}</div> + +<p>是一個正值，它代表機器能夠等待方法回傳位置的最長時間（單位是毫秒）。預設值是<code><a href="https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Infinity">Infinity</a></code>，代表 <code>getCurrentPosition()</code> 此方法在沒有可用的位置前不會有任何回覆。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><var>positionOptions</var>.timeout = <var>timeLength</var> +</pre> + +<h2 id="規格">規格</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('Geolocation', '#timeout', 'PositionOptions.timeout')}}</td> + <td>{{Spec2('Geolocation')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器的相容性">瀏覽器的相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>5</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>9</td> + <td>10.60<br> + {{CompatNo}} 15.0<br> + 16.0</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("4")}}</td> + <td>{{CompatUnknown}}</td> + <td>10.60</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="請參考">請參考</h2> + +<ul> + <li><a href="/en-US/docs/WebAPI/Using_geolocation">Using geolocation</a></li> + <li>屬於{{domxref("PositionOptions")}} 。</li> +</ul> diff --git a/files/zh-tw/web/api/progressevent/index.html b/files/zh-tw/web/api/progressevent/index.html new file mode 100644 index 0000000000..250df9b338 --- /dev/null +++ b/files/zh-tw/web/api/progressevent/index.html @@ -0,0 +1,161 @@ +--- +title: ProgressEvent +slug: Web/API/ProgressEvent +translation_of: Web/API/ProgressEvent +--- +<p>{{APIRef("DOM Events")}}</p> + +<p>The <strong><code>ProgressEvent</code></strong> interface represents events measuring progress of an underlying process, like an HTTP request (for an <code>XMLHttpRequest</code>, or the loading of the underlying resource of an {{HTMLElement("img")}}, {{HTMLElement("audio")}}, {{HTMLElement("video")}}, {{HTMLElement("style")}} or {{HTMLElement("link")}}).</p> + +<h2 id="建構式">建構式</h2> + +<dl> + <dt>{{domxref("ProgressEvent.ProgressEvent", "ProgressEvent()")}}</dt> + <dd>Creates a <code>ProgressEvent</code> event with the given parameters.</dd> +</dl> + +<h2 id="屬性">屬性</h2> + +<p><em>Also inherits properties from its parent {{domxref("Event")}}</em>.</p> + +<dl> + <dt>{{domxref("ProgressEvent.lengthComputable")}} {{readonlyInline}}</dt> + <dd>Is a {{domxref("Boolean")}} flag indicating if the total work to be done, and the amount of work already done, by the underlying process is calculable. In other words, it tells if the progress is measurable or not.</dd> + <dt>{{domxref("ProgressEvent.loaded")}} {{readonlyInline}}</dt> + <dd>Is an <code>unsigned long long</code> representing the amount of work already performed by the underlying process. The ratio of work done can be calculated with the property and <code>ProgressEvent.total</code>. When downloading a resource using HTTP, this only represent the part of the content itself, not headers and other overhead.</dd> + <dt>{{domxref("ProgressEvent.total")}} {{readonlyInline}}</dt> + <dd>Is an <code>unsigned long long</code> representing the total amount of work that the underlying process is in the progress of performing. When downloading a resource using HTTP, this only represent the content itself, not headers and other overhead.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<dl> +</dl> + +<p><em>Also inherits methods <em>from its parent {{domxref("Event")}}.</em></em></p> + +<dl> + <dt>{{domxref("ProgressEvent.initProgressEvent()")}} {{deprecated_inline}}{{non-Standard_inline}}</dt> + <dd>Initializes a <code>ProgressEvent</code> created using the deprecated {{domxref("Document.createEvent()", "Document.createEvent(\"ProgressEvent\")")}} method.</dd> +</dl> + +<h2 id="範例">範例</h2> + +<p>The following example adds a <code>ProgressEvent</code> to a new {{domxref("XMLHTTPRequest")}} and uses it to display the status of the request.</p> + +<pre class="brush: js"> var progressBar = document.getElementById("p"), + client = new XMLHttpRequest() + client.open("GET", "magical-unicorns") + client.onprogress = function(pe) { + if(pe.lengthComputable) { + progressBar.max = pe.total + progressBar.value = pe.loaded + } + } + client.onloadend = function(pe) { + progressBar.value = pe.loaded + } + client.send()</pre> + +<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('Progress Events', '#interface-progressevent', 'ProgressEvent')}}</td> + <td>{{Spec2('Progress Events')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>1.0</td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>10.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>initProgressEvent()</code> {{non-standard_inline}}{{deprecated_inline}}</td> + <td>{{CompatNo}}<sup>[1]</sup></td> + <td>{{CompatNo}}<sup>[2]</sup></td> + <td>10.0</td> + <td>{{CompatNo}}<sup>[4]</sup></td> + <td>{{CompatNo}}<sup>[3]</sup></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>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + <th>Chrome for Android</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("1.9.1")}}</td> + <td>10.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>initProgressEvent()</code> {{non-standard_inline}}{{deprecated_inline}}</td> + <td>{{CompatNo}}<sup>[3]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}<sup>[2]</sup></td> + <td>10.0</td> + <td>{{CompatNo}}<sup>[4]</sup></td> + <td>{{CompatNo}}<sup>[3]</sup></td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] This feature was implemented in Chrome 1.0, but removed in Chrome 17.0.</p> + +<p>[2] This feature was implemented in Gecko 1.9.1 {{geckoRelease("1.9.1")}}, but removed in Gecko 22 {{geckoRelease("22")}}.</p> + +<p>[3] This feature was removed at some point.</p> + +<p>[4] This feature was removed in Opera 15.0.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>The {{domxref("Event")}} base interface.</li> +</ul> diff --git a/files/zh-tw/web/api/proximity_events/index.html b/files/zh-tw/web/api/proximity_events/index.html new file mode 100644 index 0000000000..f6464480f8 --- /dev/null +++ b/files/zh-tw/web/api/proximity_events/index.html @@ -0,0 +1,118 @@ +--- +title: Proximity +slug: Web/API/Proximity_Events +translation_of: Web/API/Proximity_Events +--- +<p>{{ SeeCompatTable }}</p> +<h2 id="摘要">摘要</h2> +<p>近距 (Proximity) 事件可迅速感測出使用者靠近裝置，並迅速做出反應。舉例來說，當使用者接通來電並將裝置靠近耳朵時，智慧型手機隨即關閉螢幕。</p> +<div class="note"> + <p><strong>注意：</strong>顯然裝置必須具備近距感測器 (Proximity sensor)，此 API 才能發揮作用。而目前幾乎只有行動裝置搭載接近感測器。若裝置並未搭載感測器，則雖同樣可支援，但永遠不會觸發此類事件。</p> +</div> +<h2 id="近距事件">近距事件</h2> +<p>只要近距感測器測得「裝置」與「物體」之間的距離改變時，就會通知瀏覽器這項變化。而只要瀏覽器獲得通知，隨即啟動 <a href="https://developer.mozilla.org/en-US/docs/Web/API/DeviceProximityEvent" title="/en-US/docs/Web/API/DeviceProximityEvent"><code>DeviceProximityEvent</code></a> 以因應任何變化；或啟動 <a href="https://developer.mozilla.org/en-US/docs/Web/API/UserProximityEvent" title="/en-US/docs/Web/API/UserProximityEvent"><code>UserProximityEvent</code></a> 以因應簡單的變化。</p> +<p>透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget.addEventListener" title="/en-US/docs/Web/API/EventTarget.addEventListener"><code>addEventListener</code></a> 函式 (使用 {{event("deviceproximity")}} 或 {{event("userproximity")}} 事件名稱)；或將事件處理器 (Event handler) 附掛至 <a href="https://developer.mozilla.org/en-US/docs/Web/API/window.ondeviceproximity" title="/en-US/docs/Web/API/window.ondeviceproximity"><code>window.ondeviceproximity</code></a> 或 <a href="https://developer.mozilla.org/en-US/docs/Web/API/window.onuserproximity" title="/en-US/docs/Web/API/window.onuserproximity"><code>window.onuserproximity</code></a> 屬性，均可於 <code>window 物件層級就擷取到此事件。</code></p> +<p>在擷取事件之後，事件物件將可存取不同的資訊：</p> +<ul> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/DeviceProximityEvent" title="/en-US/docs/Web/API/DeviceProximityEvent"><code>DeviceProximityEvent</code></a> 事件透過本身的 <a href="https://developer.mozilla.org/en-US/docs/Web/API/DeviceProximityEvent.value" title="/en-US/docs/Web/API/DeviceProximityEvent.value"><code>value</code></a> 屬性，可提供裝置與物體之間的確實距離。另透過本身的 <a href="https://developer.mozilla.org/en-US/docs/Web/API/DeviceProximityEvent.min" title="/en-US/docs/Web/API/DeviceProximityEvent.min"><code>min</code></a> 與 <a href="https://developer.mozilla.org/en-US/docs/Web/API/DeviceProximityEvent.max" title="/en-US/docs/Web/API/DeviceProximityEvent.max"><code>max</code></a> 屬性，則能設定「裝置測得某物」的最近與最遠距離。</li> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/UserProximityEvent" title="/en-US/docs/Web/API/UserProximityEvent"><code>UserProximityEvent</code></a> 事件則提供粗略的距離，並以 Boolean 值呈現。物體靠近時，<a href="https://developer.mozilla.org/en-US/docs/Web/API/UserProximityEvent.near" title="/en-US/docs/Web/API/UserProximityEvent.near"><code>UserProximityEvent.near</code></a> 屬性即為 <code>true</code>；物體遠離則為 <code>false。</code></li> +</ul> +<h2 id="範例">範例</h2> +<pre class="brush: js">window.addEventListener('userproximity', function(event) { + if (event.near) { + // let's power off the screen + navigator.mozPower.screenEnabled = false; + } else { + // Otherwise, let's power on the screen + navigator.mozPower.screenEnabled = true; + } +});</pre> +<h2 id="Specifications" name="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('Proximity Events', '', 'Proximity Events') }}</td> + <td>{{ Spec2('Proximity Events') }}</td> + <td>Initial specification</td> + </tr> + </tbody> +</table> +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> +<p>{{ CompatibilityTable() }}</p> +<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>{{domxref("DeviceProximityEvent")}}</td> + <td>{{CompatNo()}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{CompatNo()}}</td> + <td>{{CompatNo()}}</td> + <td>{{CompatNo()}}</td> + </tr> + <tr> + <td>{{domxref("UserProximityEvent")}}</td> + <td>{{CompatNo()}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{CompatNo()}}</td> + <td>{{CompatNo()}}</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>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>{{domxref("DeviceProximityEvent")}}</td> + <td>{{CompatNo()}}</td> + <td>{{CompatNo()}}</td> + <td>{{ CompatGeckoMobile("15.0") }}</td> + <td>{{CompatNo()}}</td> + <td>{{CompatNo()}}</td> + <td>{{CompatNo()}}</td> + </tr> + <tr> + <td>{{domxref("UserProximityEvent")}}</td> + <td>{{CompatNo()}}</td> + <td>{{CompatNo()}}</td> + <td>{{CompatVersionUnknown()}}</td> + <td>{{CompatNo()}}</td> + <td>{{CompatNo()}}</td> + <td>{{CompatNo()}}</td> + </tr> + </tbody> + </table> +</div> +<h2 id="另可參閱">另可參閱</h2> +<ul> + <li>{{domxref("DeviceProximityEvent")}}</li> + <li>{{domxref("UserProximityEvent")}}</li> + <li>{{event("deviceproximity")}}</li> + <li>{{event("userproximity")}}</li> +</ul> diff --git a/files/zh-tw/web/api/range/index.html b/files/zh-tw/web/api/range/index.html new file mode 100644 index 0000000000..35307c4628 --- /dev/null +++ b/files/zh-tw/web/api/range/index.html @@ -0,0 +1,249 @@ +--- +title: Range +slug: Web/API/Range +translation_of: Web/API/Range +--- +<p>{{ APIRef("DOM") }}</p> + +<p><strong><code>Range</code></strong> 介面代表一個文件的片段（fragment），可以包含節點及部分的文字節點。</p> + +<p>A range can be created using the {{ domxref("Document.createRange", "createRange()") }} method of the {{ domxref("Document") }} object. Range objects can also be retrieved by using the {{ domxref("Selection/getRangeAt", "getRangeAt()") }} method of the {{ domxref("Selection") }} object or the {{domxref("Document/caretRangeFromPoint", "caretRangeFromPoint()")}} method of the {{domxref("Document")}} object.</p> + +<p>There also is the {{domxref("Range.Range()", "Range()")}} constructor available.</p> + +<h2 id="Properties" name="Properties">屬性</h2> + +<p><em>There are no inherited properties.</em></p> + +<dl> + <dt>{{domxref("Range.collapsed")}} {{readonlyInline}}</dt> + <dd>Returns a {{domxref("Boolean")}} indicating whether the range's start and end points are at the same position.</dd> + <dt>{{domxref("Range.commonAncestorContainer")}} {{readonlyInline}}</dt> + <dd>Returns the deepest {{ domxref("Node") }} that contains the <code>startContainer</code> and <code>endContainer</code> nodes.</dd> + <dt>{{domxref("Range.endContainer")}} {{readonlyInline}}</dt> + <dd>Returns the {{ domxref("Node") }} within which the <code>Range</code> ends.</dd> + <dt>{{domxref("Range.endOffset")}} {{readonlyInline}}</dt> + <dd>Returns a number representing where in the <code>endContainer</code> the <code>Range</code> ends.</dd> + <dt>{{domxref("Range.startContainer")}} {{readonlyInline}}</dt> + <dd>Returns the {{ domxref("Node") }} within which the <code>Range</code> starts.</dd> + <dt>{{domxref("Range.startOffset")}} {{readonlyInline}}</dt> + <dd>Returns a number representing where in the <code>startContainer</code> the <code>Range</code> starts.</dd> +</dl> + +<h2 id="建構式">建構式</h2> + +<dl> + <dt>{{ domxref("Range.Range()", "Range()") }} {{experimental_inline}}</dt> + <dd>Returns a <code>Range</code> object with the global {{domxref("Document")}} as its start and end.</dd> +</dl> + +<h2 id="Methods" name="Methods">方法</h2> + +<p><em>There are no inherited methods.</em></p> + +<dl> + <dt>{{ domxref("Range.setStart()")}}</dt> + <dd>Sets the start position of a <code>Range</code>.</dd> + <dt>{{ domxref("Range.setEnd()")}}</dt> + <dd>Sets the end position of a <code>Range</code>.</dd> + <dt>{{ domxref("Range.setStartBefore()")}}</dt> + <dd>Sets the start position of a <code>Range</code> relative to another {{ domxref("Node") }}.</dd> + <dt>{{ domxref("Range.setStartAfter()")}}</dt> + <dd>Sets the start position of a <code>Range</code> relative to another {{ domxref("Node") }}.</dd> + <dt>{{ domxref("Range.setEndBefore()")}}</dt> + <dd>Sets the end position of a <code>Range</code> relative to another {{ domxref("Node") }}.</dd> + <dt>{{ domxref("Range.setEndAfter()")}}</dt> + <dd>Sets the end position of a <code>Range</code> relative to another {{ domxref("Node") }}.</dd> + <dt>{{ domxref("Range.selectNode()")}}</dt> + <dd>Sets the <code>Range</code> to contain the {{ domxref("Node") }} and its contents.</dd> + <dt>{{ domxref("Range.selectNodeContents()")}}</dt> + <dd>Sets the <code>Range</code> to contain the contents of a {{ domxref("Node") }}.</dd> + <dt>{{ domxref("Range.collapse()")}}</dt> + <dd>Collapses the <code>Range</code> to one of its boundary points.</dd> + <dt>{{ domxref("Range.cloneContents()")}}</dt> + <dd>Returns a {{ domxref("DocumentFragment") }} copying the nodes of a <code>Range</code>.</dd> + <dt>{{ domxref("Range.deleteContents()")}}</dt> + <dd>Removes the contents of a <code>Range</code> from the {{ domxref("Document") }}.</dd> + <dt>{{ domxref("Range.extractContents()")}}</dt> + <dd>Moves contents of a <code>Range</code> from the document tree into a {{ domxref("DocumentFragment") }}.</dd> + <dt>{{ domxref("Range.insertNode()")}}</dt> + <dd>Insert a {{ domxref("Node") }} at the start of a <code>Range</code>.</dd> + <dt>{{ domxref("Range.surroundContents()")}}</dt> + <dd>Moves content of a <code>Range</code> into a new {{ domxref("Node") }}.</dd> + <dt>{{ domxref("Range.compareBoundaryPoints()")}}</dt> + <dd>Compares the boundary points of the <code>Range</code> with another <code>Range</code>.</dd> + <dt>{{ domxref("Range.cloneRange()")}}</dt> + <dd>Returns a <code>Range</code> object with boundary points identical to the cloned <code>Range</code>.</dd> + <dt>{{ domxref("Range.detach()")}}</dt> + <dd>Releases the <code>Range</code> from use to improve performance.</dd> + <dt>{{ domxref("Range.toString()")}}</dt> + <dd>Returns the text of the <code>Range</code>.</dd> + <dt>{{ domxref("Range.compareNode()")}} {{ Obsolete_inline }}{{non-standard_inline}}</dt> + <dd>Returns a constant representing whether the {{domxref("Node")}} is before, after, inside, or surrounding the range.</dd> + <dt>{{ domxref("Range.comparePoint()")}} {{experimental_inline}}</dt> + <dd>Returns -1, 0, or 1 indicating whether the point occurs before, inside, or after the <code>Range</code>.</dd> + <dt>{{ domxref("Range.createContextualFragment()")}}{{experimental_inline}}</dt> + <dd>Returns a {{ domxref("DocumentFragment") }} created from a given string of code.</dd> + <dt>{{ domxref("Range.getBoundingClientRect()") }} {{experimental_inline}}</dt> + <dd>Returns a {{ domxref("DOMRect") }} object which bounds the entire contents of the <code>Range</code>; this would be the union of all the rectangles returned by {{ domxref("range.getClientRects()") }}.</dd> + <dt>{{ domxref("Range.getClientRects()") }} {{experimental_inline}}</dt> + <dd>Returns a list of {{ domxref("DOMRect") }} objects that aggregates the results of {{ domxref("Element.getClientRects()") }} for all the elements in the <code>Range</code>.</dd> + <dt>{{ domxref("Range.intersectsNode()")}} {{experimental_inline}}</dt> + <dd>Returns a <code>boolean</code> indicating whether the given node intersects the <code>Range</code>.</dd> + <dt>{{ domxref("Range.isPointInRange()")}} {{experimental_inline}}</dt> + <dd>Returns a <code>boolean</code> indicating whether the given point is in the <code>Range</code>.</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('DOM WHATWG', '#interface-range', 'Range')}}</td> + <td>{{Spec2('DOM WHATWG')}}</td> + <td>Do not use <code>RangeException</code> anymore, use <code>DOMException</code> instead.<br> + Made the second parameter of <code>collapse()</code> optional.<br> + Added the methods <code>isPointInRange()</code>, <code>comparePoint()</code>, and <code>intersectsNode()</code>.<br> + Added the constructor <code>Range()</code>.</td> + </tr> + <tr> + <td>{{SpecName('DOM Parsing', '#extensions-to-the-range-interface', 'Extensions to Range')}}</td> + <td>{{Spec2('DOM Parsing')}}</td> + <td>Added the method <code>createContextualFragment()</code>.</td> + </tr> + <tr> + <td>{{SpecName('CSSOM View', '#extensions-to-the-range-interface', 'Extensions to Range')}}</td> + <td>{{Spec2('CSSOM View')}}</td> + <td>Added the methods <code>getClientRects()</code> and <code>getBoundingClientRect()</code>.</td> + </tr> + <tr> + <td>{{SpecName('DOM2 Traversal_Range', 'ranges.html#Level-2-Range-Interface', 'Range')}}</td> + <td>{{Spec2('DOM2 Traversal_Range')}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1.0")}} [1]</td> + <td>9.0</td> + <td>9.0</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>Range()</code> constructor {{experimental_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoDesktop("24.0")}}</td> + <td>{{CompatNo}}</td> + <td>15.0</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>compareNode()</code> {{obsolete_inline}}{{non-standard_inline()}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoDesktop("1.0")}}<br> + Removed in {{CompatGeckoDesktop("1.9")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>isPointInRange()</code>, and <code>comparePoint()</code>{{experimental_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>15.0</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>intersectsNode()</code> {{experimental_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoDesktop("17.0")}} [2]</td> + <td>{{CompatNo}}</td> + <td>15.0</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>getClientRects()</code> and <code>getBoundingClientRect()</code>{{experimental_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("2.0")}}</td> + <td>9</td> + <td>15.0</td> + <td>5</td> + </tr> + <tr> + <td><code>createContextualFragment()</code>{{experimental_inline}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>11</td> + <td>15.0</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("1.0")}} [1]</td> + <td>9.0</td> + <td>9.0</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Starting with Gecko 13.0 {{ geckoRelease("13.0") }} the <code>Range</code> object throws a {{ domxref("DOMException") }} as defined in DOM 4, instead of a <code>RangeException</code> defined in prior specifications.</p> + +<p>[2] Gecko supported it up to Gecko 1.9, then removed it until Gecko 17 where it was reimplemented, matching the spec.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/en-US/docs/DOM/DOM_Reference" title="/en-US/docs/DOM/DOM_Reference">The DOM interfaces index</a></li> +</ul> diff --git a/files/zh-tw/web/api/response/index.html b/files/zh-tw/web/api/response/index.html new file mode 100644 index 0000000000..8899c22fa5 --- /dev/null +++ b/files/zh-tw/web/api/response/index.html @@ -0,0 +1,120 @@ +--- +title: Response +slug: Web/API/Response +translation_of: Web/API/Response +--- +<div>{{APIRef("Fetch API")}}</div> + +<p><a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a> 的 <strong><code>Response</code></strong> 介面代表了一個請求會返回的回應。</p> + +<p>你可以用 {{domxref("Response.Response()")}} 建構子創建一個新的 <code>Response</code>物件。但實務上碰到 Response 物件的時機，比較常出現在進行了一個 API 操作後，得到返回的 Response 物件。舉例而言，使用 service worker {{domxref("Fetchevent.respondWith")}} 或是使用單純的{{domxref("GlobalFetch.fetch()")}}。</p> + +<h2 id="建構子">建構子</h2> + +<dl> + <dt>{{domxref("Response.Response","Response()")}}</dt> + <dd>創建一個新的 <code>Response</code> 物件。</dd> +</dl> + +<h2 id="屬性">屬性</h2> + +<dl> + <dt>{{domxref("Response.headers")}} {{readonlyinline}}</dt> + <dd>包含與此 response 相關的 {{domxref("Headers")}} 物件。</dd> + <dt>{{domxref("Response.ok")}} {{readonlyinline}}</dt> + <dd>無論此 response 是不是成功 ( 狀態碼 200-299 ) 都會包含一個 boolean 狀態。</dd> + <dt>{{domxref("Response.redirected")}} {{ReadOnlyInline}}</dt> + <dd>指出此 response 是不是個重新導向的結果，如果是的話，代表此 URL 具有一個以上的入口。</dd> + <dt>{{domxref("Response.status")}} {{readonlyinline}}</dt> + <dd>包含此 response 的狀態碼(例如：成功時為 <code>200</code> )。</dd> + <dt>{{domxref("Response.statusText")}} {{readonlyinline}}</dt> + <dd>包含狀態碼所對應的狀態文字 (例如： <code>OK</code> 對應 <code>200</code>)。</dd> + <dt>{{domxref("Response.type")}} {{readonlyinline}}</dt> + <dd>包含此 response 的類型 (例如： <code>basic</code>, <code>cors</code>)。</dd> + <dt>{{domxref("Response.url")}} {{readonlyinline}}</dt> + <dd>包含此 response 的 URL。</dd> + <dt>{{domxref("Response.useFinalURL")}}</dt> + <dd>包含一個 boolean 狀態，指出此 URL 是否為此 response 的最後一步。</dd> +</dl> + +<p><code>Response</code> 實做了{{domxref("Body")}}, 所以它另有以下可用的屬性：</p> + +<dl> + <dt>{{domxref("Body.body")}} {{readonlyInline}}</dt> + <dd>A simple getter used to expose a {{domxref("ReadableStream")}} of the body contents.</dd> + <dt>{{domxref("Body.bodyUsed")}} {{readonlyInline}}</dt> + <dd>Stores a {{domxref("Boolean")}} that declares whether the body has been used in a response yet.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<dl> + <dt>{{domxref("Response.clone()")}}</dt> + <dd>建立一份 <code>Response</code> 的複製物件。</dd> + <dt>{{domxref("Response.error()")}}</dt> + <dd>Returns a new <code>Response</code> object associated with a network error.</dd> + <dt>{{domxref("Response.redirect()")}}</dt> + <dd>Creates a new response with a different URL.</dd> +</dl> + +<p><code>Response</code> implements {{domxref("Body")}}, so it also has the following methods available to it:</p> + +<dl> + <dt>{{domxref("Body.arrayBuffer()")}}</dt> + <dd>Takes a {{domxref("Response")}} stream and reads it to completion. It returns a promise that resolves with an {{domxref("ArrayBuffer")}}.</dd> + <dt>{{domxref("Body.blob()")}}</dt> + <dd>Takes a {{domxref("Response")}} stream and reads it to completion. It returns a promise that resolves with a {{domxref("Blob")}}.</dd> + <dt>{{domxref("Body.formData()")}}</dt> + <dd>Takes a {{domxref("Response")}} stream and reads it to completion. It returns a promise that resolves with a {{domxref("FormData")}} object.</dd> + <dt>{{domxref("Body.json()")}}</dt> + <dd>Takes a {{domxref("Response")}} stream and reads it to completion. It returns a promise that resolves with the result of parsing the body text as {{jsxref("JSON")}}.</dd> + <dt>{{domxref("Body.text()")}}</dt> + <dd>Takes a {{domxref("Response")}} stream and reads it to completion. It returns a promise that resolves with a {{domxref("USVString")}} (text).</dd> +</dl> + +<h2 id="範例">範例</h2> + +<p>在<a href="https://github.com/mdn/fetch-examples/tree/master/basic-fetch">基本 fetch 範例</a> (<a href="http://mdn.github.io/fetch-examples/basic-fetch/">run example live</a>) 中，我們使用<span style="font-size: 1rem; letter-spacing: -0.00278rem;"> </span><code style="font-size: 1rem; letter-spacing: -0.00278rem;">fetch()</code><span style="font-size: 1rem; letter-spacing: -0.00278rem;"> 呼叫來得到圖片，並使用 {{htmlelement("img")}} tag 顯示。 這裡的</span><code style="font-size: 1rem; letter-spacing: -0.00278rem;">fetch()</code><span style="font-size: 1rem; letter-spacing: -0.00278rem;"> 呼叫返回了一個 promise，它使用與資源 fetch 操作有關的 </span><code style="font-size: 1rem; letter-spacing: -0.00278rem;">Response</code><span style="font-size: 1rem; letter-spacing: -0.00278rem;"> 進行解析。你可能有發現，由於我們要求的是一張圖片，所以需要用 {{domxref("Body.blob")}} ({{domxref("Response")}} 時做了 body) 讓 response 有正確的 MIME 類型。</span></p> + +<pre class="brush: js">const image = document.querySelector('.my-image'); +fetch('flowers.jpg').then(function(response) { + return response.blob(); +}).then(function(blob) { + const objectURL = URL.createObjectURL(blob); + image.src = objectURL; +});</pre> + +<p>除此之外，你也能用 {{domxref("Response.Response()")}} 建構子去建立自己的客製化 <code>Response</code> 物件：</p> + +<pre class="brush: js">const response = new Response();</pre> + +<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('Fetch','#response-class','Response')}}</td> + <td>{{Spec2('Fetch')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + + + +<p>{{Compat("api.Response")}}</p> + +<h2 id="參考">參考</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/ServiceWorker_API">ServiceWorker API</a></li> + <li><a href="/en-US/docs/Web/HTTP/Access_control_CORS">HTTP access control (CORS)</a></li> + <li><a href="/en-US/docs/Web/HTTP">HTTP</a></li> +</ul> diff --git a/files/zh-tw/web/api/screen/index.html b/files/zh-tw/web/api/screen/index.html new file mode 100644 index 0000000000..089203003f --- /dev/null +++ b/files/zh-tw/web/api/screen/index.html @@ -0,0 +1,89 @@ +--- +title: Screen +slug: Web/API/Screen +translation_of: Web/API/Screen +--- +<div>{{APIRef("CSSOM View")}}</div> + +<p><code>Screen</code> 介面表示了一個用戶端螢幕，通常是指呈現目前頁面的視窗。</p> + +<p>一般來說為顯示目前網頁的視窗，可以透過 <code>window.screen</code> 取得物件實體。</p> + +<h2 id="Example" name="Example">屬性</h2> + +<dl> + <dt>{{domxref("Screen.availTop")}}</dt> + <dd>Specifies the y-coordinate of the first pixel that is not allocated to permanent or semipermanent user interface features.</dd> + <dt>{{domxref("Screen.availLeft")}}</dt> + <dd>Returns the first available pixel available from the left side of the screen.</dd> + <dt>{{domxref("Screen.availHeight")}}</dt> + <dd>Specifies the height of the screen, in pixels, minus permanent or semipermanent user interface features displayed by the operating system, such as the Taskbar on Windows.</dd> + <dt>{{domxref("Screen.availWidth")}}</dt> + <dd>Returns the amount of horizontal space in pixels available to the window.</dd> + <dt>{{domxref("Screen.colorDepth")}}</dt> + <dd>Returns the color depth of the screen.</dd> + <dt>{{domxref("Screen.height")}}</dt> + <dd>Returns the height of the screen in pixels.</dd> + <dt>{{domxref("Screen.left")}}</dt> + <dd>Returns the distance in pixels from the left side of the main screen to the left side of the current screen.</dd> + <dt>{{domxref("Screen.orientation")}}</dt> + <dd>Returns the current orientation of the screen.</dd> + <dt>{{domxref("Screen.pixelDepth")}}</dt> + <dd>Gets the bit depth of the screen.</dd> + <dt>{{domxref("Screen.top")}}</dt> + <dd>Returns the distance in pixels from the top side of the current screen.</dd> + <dt>{{domxref("Screen.width")}}</dt> + <dd>Returns the width of the screen.</dd> + <dt>{{domxref("Screen.mozEnabled")}} {{gecko_minversion_inline("12.0")}}</dt> + <dd>Boolean. Setting to false will turn off the device's screen.</dd> + <dt>{{domxref("Screen.mozBrightness")}} {{gecko_minversion_inline("12.0")}}</dt> + <dd>Controls the brightness of a device's screen. A double between 0 and 1.0 is expected.</dd> +</dl> + +<h3 id="事件處理器">事件處理器</h3> + +<dl> + <dt>{{domxref("Screen.onorientationchange")}}</dt> + <dd>A handler for the {{event("orientationchange")}} events.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<dl> + <dt>{{domxref("Screen.lockOrientation")}}</dt> + <dd>Lock the screen orientation (only works in fullscreen or for installed apps)</dd> + <dt>{{domxref("Screen.unlockOrientation")}}</dt> + <dd>Unlock the screen orientation (only works in fullscreen or for installed apps)</dd> +</dl> + +<p>Methods inherit from {{domxref("EventTarget")}}</p> + +<p>{{page("/en-US/docs/Web/API/EventTarget","Methods")}}</p> + +<h2 id="Example" name="Example">範例</h2> + +<pre class="brush:js">if (screen.pixelDepth < 8) { + // use low-color version of page +} else { + // use regular, colorful page +} +</pre> + +<h2 id="Specification" name="Specification">規範</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('CSSOM View', '#the-screen-interface', 'Screen') }}</td> + <td>{{ Spec2('CSSOM View') }}</td> + <td> </td> + </tr> + </tbody> +</table> diff --git a/files/zh-tw/web/api/screen/orientation/index.html b/files/zh-tw/web/api/screen/orientation/index.html new file mode 100644 index 0000000000..eafa89a703 --- /dev/null +++ b/files/zh-tw/web/api/screen/orientation/index.html @@ -0,0 +1,114 @@ +--- +title: Screen.orientation +slug: Web/API/Screen/orientation +translation_of: Web/API/Screen/orientation +--- +<div>{{APIRef("CSSOM View")}}{{SeeCompatTable}}</div> + +<p><code>Screen.orientation</code> 屬性可以取得螢幕目前的方向。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">var orientation = window.screen.orientation.type; +</pre> + +<h2 id="回傳值">回傳值</h2> + +<p>回傳值為一個代表螢幕方向的字串，可能是 <code>portrait-primary</code>、<code>portrait-secondary</code>、<code>landscape-primary</code> 或 <code>landscape-secondary</code>（請參考 {{domxref("window.screen.lockOrientation","lockOrientation")}} 以瞭解更多資訊）。</p> + +<h2 id="範例">範例</h2> + +<pre class="brush: js">var orientation = screen.orientation || screen.mozOrientation || screen.msOrientation; + +if (orientation.type === "landscape-primary") { + console.log("That looks good."); +} else if (orientation.type === "landscape-secondary") { + console.log("Mmmh... the screen is upside down!"); +} else if (orientation.type === "portrait-secondary" || orientation.type === "portrait-primary") { + console.log("Mmmh... you should rotate your device to landscape"); +} +</pre> + +<h2 id="規範">規範</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('Screen Orientation', '', 'Screen Orientation')}}</td> + <td>{{Spec2('Screen Orientation')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>38</td> + <td>{{CompatVersionUnknown}} {{property_prefix("moz")}}<sup>[1]</sup></td> + <td>11{{property_prefix("ms")}}<sup>[2]</sup></td> + <td>25</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>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatNo}}</td> + <td>39</td> + <td>{{CompatVersionUnknown}} {{property_prefix("moz")}}<sup>[1]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] This API is only implemented as a prefixed method (<code>mozOrientation</code>) in B2G and Firefox for Android.</p> + +<p>[2] This API is implemented using a prefix (<code>msOrientation</code>) in Internet Explorer for Windows 8.1 and Windows RT 8.1. It is not supported on Windows 7.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("Screen.orientation")}}</li> + <li>{{domxref("Screen.unlockOrientation()")}}</li> + <li>{{domxref("Screen.onorientationchange")}}</li> + <li><a href="/zh-TW/docs/Web/API/CSS_Object_Model/Managing_screen_orientation">控制畫面方向</a></li> +</ul> diff --git a/files/zh-tw/web/api/server-sent_events/index.html b/files/zh-tw/web/api/server-sent_events/index.html new file mode 100644 index 0000000000..bb72cb3f93 --- /dev/null +++ b/files/zh-tw/web/api/server-sent_events/index.html @@ -0,0 +1,115 @@ +--- +title: Server-sent events +slug: Web/API/Server-sent_events +translation_of: Web/API/Server-sent_events +--- +<p>網頁一般來說是由客戶端向伺服器請求資料. 藉由 server-sent 事件, 伺服器在任何時候都可以向客戶端推送資料. 即將推送進來的訊息可以自客戶端上做 <em><a href="/en-US/docs/DOM/event" title="DOM/Event">Events</a> + data </em>處理.</p> + +<table class="topicpage-table"> + <tbody> + <tr> + <td> + <h2 class="Documentation" id="Documentation" name="Documentation">文件</h2> + + <dl> + <dt>使用 <a href="/en-US/docs/Server-sent_events/Using_server-sent_events" title="Server-sent events/Using server-sent events">server-sent events</a></dt> + <dd>有關如何在伺服器端和客戶端使用 server-sent 事件的教學文章.</dd> + <dt>參考 <a href="/en-US/docs/Server-sent_events/EventSource" title="Server-sent events/EventSource">EventSource</a></dt> + <dd>關於客戶端的 EventSource API.</dd> + </dl> + + <p><span class="alllinks"><a href="/en-US/docs/tag/Server-sent_events" title="tag/Server-sent events">瀏覽全部...</a></span></p> + </td> + <td> + <h2 class="Tools" id="Tools" name="Tools">工具</h2> + + <ul> + <li>Remy Sharp’s <a class="link-https" href="https://github.com/remy/polyfills/blob/master/EventSource.js">EventSource polyfill</a></li> + <li>Yaffle’s <a class="link-https" href="https://github.com/Yaffle/EventSource" title="https://github.com/Yaffle/EventSource">EventSource polyfill</a></li> + <li>Rick Waldron’s <a class="link-https" href="https://github.com/rwldrn/jquery.eventsource">jquery plugin</a></li> + </ul> + + <h2 class="Related_Topics" id="Related_Topics" name="Related_Topics">相關主題</h2> + + <ul> + <li><a href="/en-US/docs/AJAX" title="AJAX">AJAX</a>, <a href="/en-US/docs/JavaScript" title="JavaScript">JavaScript</a>, <a href="/en-US/docs/WebSockets" title="WebSockets">WebSockets</a></li> + </ul> + </td> + </tr> + </tbody> +</table> + +<h2 id="參見">參見</h2> + +<ul> + <li>A <a href="http://hacks.mozilla.org/2011/06/a-wall-powered-by-eventsource-and-server-sent-events/" title="http://hacks.mozilla.org/2011/06/a-wall-powered-by-eventsource-and-server-sent-events/">Twitter like application</a> powered by server-sent events and <a class="link-https" href="https://github.com/mozilla/webowonder-demos/tree/master/demos/friends%20timeline" title="https://github.com/mozilla/webowonder-demos/tree/master/demos/friends timeline">its code on Github</a>.</li> + <li><a href="http://dsheiko.com/weblog/html5-and-server-sent-events" title="http://dsheiko.com/weblog/html5-and-server-sent-events">HTML5 and Server-sent events</a></li> + <li><a href="http://rajudasa.blogspot.in/2012/05/html5-server-sent-events-using-aspnet.html" title="http://rajudasa.blogspot.in/2012/05/html5-server-sent-events-using-aspnet.html">Server-sent events using Asp.Net</a></li> +</ul> + +<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('Server-sent events')}}</td> + <td>{{Spec2('Server-sent events')}}</td> + <td>Initial definition.</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>EventSource support</td> + <td>9</td> + <td>{{CompatGeckoDesktop("6.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>11</td> + <td>5</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>EventSource support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> diff --git a/files/zh-tw/web/api/server-sent_events/using_server-sent_events/index.html b/files/zh-tw/web/api/server-sent_events/using_server-sent_events/index.html new file mode 100644 index 0000000000..92433f4f18 --- /dev/null +++ b/files/zh-tw/web/api/server-sent_events/using_server-sent_events/index.html @@ -0,0 +1,202 @@ +--- +title: 使用 server-sent 事件 +slug: Web/API/Server-sent_events/Using_server-sent_events +tags: + - Advanced + - Communication + - DOM + - EventSource + - Guide + - SSE + - Server Sent Events + - Server-Sent-Event +translation_of: Web/API/Server-sent_events/Using_server-sent_events +--- +<p>{{DefaultAPISidebar("Server Sent Events")}}</p> + +<div class="summary"> +<p>開發一個使用 server-sent 事件的網頁應用程式很簡單。在伺服器端只需要一些的程式碼與網頁串流事件，而客戶端這邊的處理進入事件的部分幾乎跟 <a href="/zh-TW/docs/Web/API/WebSockets_API">websockets</a> 一樣。這是一種單向的連線，所以你無法從客戶端向伺服器傳送事件。</p> +</div> + +<h2 id="從伺服器端接收事件">從伺服器端接收事件</h2> + +<p>server-sent event API 包含在 {{domxref("EventSource")}} 介面；為了與伺服器端開啟連線並接收事件，需要建立帶有產生事件 script URL 的 {{domxref("EventSource")}} 物件。例如：</p> + +<pre class="brush: js notranslate">const evtSource = new EventSource("ssedemo.php");</pre> + +<p>如果事件產生的 script 在不同源的伺服器上，在建立 {{domxref("EventSource")}} 物件時需要同時提供 URL 和第二個參數作為選項設定。假設客戶端的 script 伺服於 <code>example.com</code> ：</p> + +<pre class="brush: js notranslate">const evtSource = new EventSource("//api.example.com/ssedemo.php", { withCredentials: true } );</pre> + +<p>當你完成初始化事件來源後，你就可以透過新增 {{event("message")}} 事件的處理器來開始監聽來自伺服器的訊息：</p> + +<pre class="brush: js notranslate">evtSource.onmessage = function(event) { + const newElement = document.createElement("li"); + const eventList = document.getElementById("list"); + + newElement.innerHTML = "message: " + event.data; + eventList.appendChild(newElement); +} +</pre> + +<p>上述的程式碼會監聽進入的訊息（這裡來自伺服器的通知沒有指明 <code>event</code> 欄位，所以統一用 <code>onmessage</code> 處理即可）並且把訊息的文字附加到 document 的清單。</p> + +<p>你也可以利用 <code>addEventListener()</code> 監聽事件：</p> + +<pre class="brush: js notranslate">evtSource.addEventListener("ping", function(event) { + const newElement = document.createElement("li"); + const time = JSON.parse(event.data).time; + newElement.innerHTML = "ping at " + time; + eventList.appendChild(newElement); +}); +</pre> + +<p>上述的程式碼大同小異，不同之處在於若伺服器傳送了 <code>event</code> 欄位值為「ping」的訊息時它就會把 <code>data</code> 欄位的值解析為 JSON 並輸出到畫面上。</p> + +<div class="blockIndicator warning"> +<p>當連線不是透過<strong> HTTP/2</strong> 時，SSE 會受到最大連線數限制所苦，尤其當開啟多個分頁。每個瀏覽器有自己的限制數而且被限制在很低的數量（6）。這個問題已經被 <a href="https://bugs.chromium.org/p/chromium/issues/detail?id=275955" rel="noreferrer">Chrome</a> 和 <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=906896" rel="noreferrer">Firefox</a> 標註為「Won't fix」（不修復）。限制是基於每個瀏覽器 + 網域，也就是說你可以針對 www.example1.com 網域在所有的分頁中開啟六個 SSE 連線，另一個網域 www.example2.com 也可以開啟六個（根據 <a href="https://stackoverflow.com/a/5326159/1905229">Stackoverflow</a>）。當使用 HTTP/2 時最大同時 <em>HTTP streams</em> 連線數是由伺服器和客戶端之間協調（預設 100）。</p> +</div> + +<h2 id="從伺服器發送事件">從伺服器發送事件</h2> + +<p>由伺服器端所發送的事件需要使用 <code>text/event-stream</code> 的 MIME 類型回應。每一個通知皆由一組文字組成並由一對換行結尾。如何處理事件串流的格式，請參考 {{ anch("Event stream format") }} 。</p> + +<p>下面是一個 {{Glossary("PHP")}} 範例：</p> + +<pre class="brush: php notranslate">date_default_timezone_set("America/New_York"); +header("Cache-Control: no-cache"); +header("Content-Type: text/event-stream"); + +$counter = rand(1, 10); +while (true) { + // Every second, send a "ping" event. + + echo "event: ping\n"; + $curDate = date(DATE_ISO8601); + echo 'data: {"time": "' . $curDate . '"}'; + echo "\n\n"; + + // Send a simple message at random intervals. + + $counter--; + + if (!$counter) { + echo 'data: This is a message at time ' . $curDate . "\n\n"; + $counter = rand(1, 10); + } + + ob_end_flush(); + flush(); + + // Break the loop if the client aborted the connection (closed the page) + + if ( connection_aborted() ) break; + + sleep(1); +} +</pre> + +<p>上述的程式碼會在每秒產生一個類型為「ping」的事件。每一個事件的資料是一個 JSON 物件，內容為事件產生時的 ISO 8601 時間戳。同時會隨機發送一個簡易訊息（沒有事件類型）。<br> + 迴圈的執行會獨立於連線的狀態，，所以在迴圈裡必須檢查連線的狀態，若斷線了要關閉連線（譬如，客戶端關閉了網頁）。</p> + +<div class="note"> +<p><strong>備註：</strong> 你可以從下列的 Github 文章中找到包含本文所使用程式碼的完整範例 —— 參考 <a href="https://github.com/mdn/dom-examples/tree/master/server-sent-events">Simple SSE demo using PHP.</a></p> +</div> + +<h2 id="錯誤處理">錯誤處理</h2> + +<p>當錯誤發生時（譬如網路逾時或有關<a href="/zh-TW/docs/Web/HTTP/CORS">存取控制</a>的問題）會產生錯誤事件。你可以透過對 <code>EventSource</code> 物件實作 <code>onerror</code> 回呼的方式採取程式化的處理：</p> + +<pre class="brush: js notranslate">evtSource.onerror = function(err) { + console.error("EventSource failed:", err); +}; +</pre> + +<h2 id="關閉事件串流">關閉事件串流</h2> + +<p>預設的情況下，如果客戶端和伺服器的連線關閉則連線會被重啟。連線的關閉會伴隨著 <code>.close()</code> 方法的執行。</p> + +<pre class="notranslate">evtSource.close();</pre> + +<h2 id="事件串流（Event_Stream）格式">事件串流（Event Stream）格式</h2> + +<p>事件串流是個簡易的文字資料串流，內容必須以 UTF-8 格式編碼。在事件串流中，不同的訊息以一對換行符號做區隔。若要撰寫註解，則要在該行的開頭加上冒號（:）。</p> + +<div class="note"><strong>備註：</strong> 註解將有助於防止連線逾時；伺服器端可以定時發送註解以維持連線活著。</div> + +<p>每一個訊息是由一到多列的欄位所組成的文字。每個欄位依序由欄位的名稱、冒號、該欄位的文字內容所組合而成。</p> + +<h3 id="欄位">欄位</h3> + +<p>每隔訊息皆可以由下列的欄位組合而成，每個欄位以換行做為區隔：</p> + +<dl> + <dt><code>event</code></dt> + <dd>事件的類型。如果有指定則在瀏覽器端會對該事件名稱的監聽器發布事件；網頁的原始碼必須使用 <code>addEventListener()</code> 來監聽已命名的事件。 <code>onmessage</code> 處理器只有在訊息沒有指定事件名稱時才會被呼叫。</dd> + <dt><code>data</code></dt> + <dd>訊息的資料欄位。當 EventSource 連續接收到多列以 <code>data:</code> 開頭的內容；<a href="http://www.w3.org/TR/eventsource/#dispatchMessage">它會串接這些內容</a>並為每一列插入一個換行字元。最後的換行會被移除。</dd> + <dt><code>id</code></dt> + <dd>{{domxref("EventSource")}} 物件的最新一個事件 ID 。</dd> + <dt><code>retry</code></dt> + <dd>當嘗試傳送事件時重新連線的時間。這個值必須是整數，單位是毫秒，作為重新連線的時間。若指定是非整數則這個欄位會被忽略。</dd> +</dl> + +<p>除上述的幾個欄位，其他欄位均會被忽略。</p> + +<div class="note"><strong>備註：</strong>如果某列的內容沒有包含冒號，則該列的內容都會被視為欄位名稱及空字串的欄位值。</div> + +<h3 id="範例">範例</h3> + +<h4 id="Data-only_訊息">Data-only 訊息</h4> + +<p>在下列的範例中，共發送了三個訊息。第一個是註解，因其以冒號開頭。如之前提到的，對不會持續發送訊息的情境下，這將有助於維持連線的存續。</p> + +<p>第二則訊息包含了 data 欄位及「some text」的值。第三則訊息包含了 data 欄位及「another message\nwith two lines」。注意在內容所出現的換行符號。</p> + +<pre class="notranslate">: this is a test stream + +data: some text + +data: another message +data: with two lines +</pre> + +<h4 id="命名事件">命名事件</h4> + +<p>這個範例傳送了一些命名的事件。每一個事件都被指定了 <code>event</code> 欄位並且 <code>data</code> 欄位也有相應的 JSON 字串作為客戶端回應事件所需的資料。 <code>data</code> 欄位的內容可以是任何的字串；它並沒有強制必須以 JSON 的格式撰寫。</p> + +<pre class="notranslate">event: userconnect +data: {"username": "bobby", "time": "02:33:48"} + +event: usermessage +data: {"username": "bobby", "time": "02:34:11", "text": "Hi everyone."} + +event: userdisconnect +data: {"username": "bobby", "time": "02:34:23"} + +event: usermessage +data: {"username": "sean", "time": "02:34:36", "text": "Bye, bobby."} +</pre> + +<h4 id="混合及配對">混合及配對</h4> + +<p>你並非一定只能用未命名訊息或已分類的事件；實際上你可以在單一的事件中把它們混合在一起。</p> + +<pre class="notranslate">event: userconnect +data: {"username": "bobby", "time": "02:33:48"} + +data: Here's a system message of some kind that will get used +data: to accomplish some task. + +event: usermessage +data: {"username": "bobby", "time": "02:34:11", "text": "Hi everyone."}</pre> + +<div> +<h3 id="EventSource"><code>EventSource</code></h3> + +<div> + + +<p>{{Compat("api.EventSource")}}</p> +</div> +</div> diff --git a/files/zh-tw/web/api/storage/index.html b/files/zh-tw/web/api/storage/index.html new file mode 100644 index 0000000000..b3990bf756 --- /dev/null +++ b/files/zh-tw/web/api/storage/index.html @@ -0,0 +1,106 @@ +--- +title: Storage +slug: Web/API/Storage +translation_of: Web/API/Storage +--- +<div> </div> + +<div>{{APIRef("Web Storage API")}}</div> + +<p><a href="/en-US/docs/Web/API/Web_Storage_API">Web Storage API</a> 中的 <strong><code>Storage</code></strong> 介面提供了存取特定 domain session 及本機儲存的方法。舉例而言，它能夠對存取的資料進行新增、刪除、修改，</p> + +<p>在操作上，如果是對象是 domain session storage ，會呼叫 {{domxref("Window.sessionStorage")}} 。而若是 local storage，則呼叫 {{domxref("Window.localStorage")}} 。</p> + +<h2 id="屬性">屬性</h2> + +<dl> + <dt>{{domxref("Storage.length")}} {{readonlyInline}}</dt> + <dd>返回一數字，代表儲存在 <code>Storage</code> 中的物件的數量。</dd> +</dl> + +<h2 id="方法">方法</h2> + +<dl> + <dt>{{domxref("Storage.key()")}}</dt> + <dd>當傳入一數字 <code>n</code>, 會返回 storage 裡第 n 個值的 key 值。</dd> +</dl> + +<dl> + <dt>{{domxref("Storage.getItem()")}}</dt> + <dd>當傳入一 key 值, 會返回 storage 裡此 key 值對應的 value 。</dd> + <dt>{{domxref("Storage.setItem()")}}</dt> + <dd>當傳入 key 及 value 的值, 會在 storage 裡新增此 key 及 value 值，若 key 已存在，則會把值更新成傳入的 value。</dd> + <dt>{{domxref("Storage.removeItem()")}}</dt> + <dd>當傳入一 key 值, 會把此 key 從 storage 裡刪除。</dd> + <dt>{{domxref("Storage.clear()")}}</dt> + <dd>執行此方法，會刪除所有在 storage 裡的 key。</dd> +</dl> + +<h2 id="範例">範例</h2> + +<p>在這裡，我們藉由呼叫 <code>localStorage</code> 來存取 <code>Storage</code> 物件，首先使用 <code>!localStorage.getItem('bgcolor')</code> 來<span style="font-size: 1rem; letter-spacing: -0.00278rem;">確認 </span><span style="font-size: 1rem; letter-spacing: -0.00278rem;">storage 裡是否有項目存在。</span></p> + +<p><span style="font-size: 1rem; letter-spacing: -0.00278rem;">如果有，則</span><span style="font-size: 1rem; letter-spacing: -0.00278rem;">執行函示</span><span style="font-size: 1rem; letter-spacing: -0.00278rem;"> </span><code style="font-size: 1rem; letter-spacing: -0.00278rem;">setStyles()</code><span style="font-size: 1rem; letter-spacing: -0.00278rem;"> ，這個函示使用 </span><span style="font-size: 1rem; letter-spacing: -0.00278rem;">{{domxref("Storage.getItem()")}} 取得 storage 的值，並且用這些值更新頁面樣式 。</span></p> + +<p>如果沒有，便執行另一個函示 <code style="font-size: 1rem; letter-spacing: -0.00278rem;">populateStorage()</code><span style="font-size: 1rem; letter-spacing: -0.00278rem;">，他使用 {{domxref("Storage.setItem()")}} 先設定 storage 項目的值，然後才執行</span><code style="font-size: 1rem; letter-spacing: -0.00278rem;">setStyles()</code>。</p> + +<pre class="brush: js">if(!localStorage.getItem('bgcolor')) { + populateStorage(); +} +setStyles(); + +function populateStorage() { + localStorage.setItem('bgcolor', document.getElementById('bgcolor').value); + localStorage.setItem('font', document.getElementById('font').value); + localStorage.setItem('image', document.getElementById('image').value); +} + +function setStyles() { + var currentColor = localStorage.getItem('bgcolor'); + var currentFont = localStorage.getItem('font'); + var currentImage = localStorage.getItem('image'); + + document.getElementById('bgcolor').value = currentColor; + document.getElementById('font').value = currentFont; + document.getElementById('image').value = currentImage; + + htmlElem.style.backgroundColor = '#' + currentColor; + pElem.style.fontFamily = currentFont; + imgElem.setAttribute('src', currentImage); +}</pre> + +<div class="note"> +<p><strong>注意</strong>: 想要看這個範例完整運行，可以參考我們的 <a href="https://mdn.github.io/dom-examples/web-storage/">Web Storage Demo</a>.</p> +</div> + +<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('HTML WHATWG', 'webstorage.html#the-storage-interface', 'Storage')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + + + +<p>{{Compat("api.Storage")}}</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API">Using the Web Storage API</a></li> + <li>{{domxref("Window.localStorage")}}</li> + <li>{{domxref("Window.sessionStorage")}}</li> + <li>{{domxref("CacheStorage")}}</li> +</ul> diff --git a/files/zh-tw/web/api/touch/index.html b/files/zh-tw/web/api/touch/index.html new file mode 100644 index 0000000000..3dc1a243b0 --- /dev/null +++ b/files/zh-tw/web/api/touch/index.html @@ -0,0 +1,207 @@ +--- +title: Touch +slug: Web/API/Touch +translation_of: Web/API/Touch +--- +<p>{{ APIRef("Touch Events") }}</p> + +<p><strong><code>Touch</code></strong> 介面表示了一個於觸控裝置上接觸的單一觸碰點。觸碰點通常是由手指或觸控筆所接觸，而裝置可能為觸控螢幕或觸控板。</p> + +<p>{{ domxref("Touch.radiusX") }}、{{ domxref("Touch.radiusY") }} 及 {{ domxref("Touch.rotationAngle") }} 描述了使用者與螢幕之間接觸的區域—<em>觸碰區（touch area）</em>，這對處理不精確的指向設備（如手指）來說相當有幫助。這些數值被用來描述一個盡可能與整個接觸面積相匹配的橢圓（如使用者的指尖）。{{experimental_inline}}</p> + +<div class="note"> +<p><strong>Note:</strong> Many of the properties' values are hardware-dependent; for example, if the device doesn't have a way to detect the amount of pressure placed on the surface, the <code>force</code> value will always be 0. This may also be the case for <code>radiusX</code> and <code>radiusY</code>; if the hardware reports only a single point, these values will be 1.</p> +</div> + +<h2 id="建構式">建構式</h2> + +<dl> + <dt>{{domxref("Touch.Touch", "Touch()")}} {{experimental_inline}}</dt> + <dd>Creates a Touch object.</dd> +</dl> + +<h2 id="屬性">屬性</h2> + +<p><em>This interface has no parent, and doesn't inherits or implements any other property.</em></p> + +<h3 id="基本屬性">基本屬性</h3> + +<dl> + <dt>{{ domxref("Touch.identifier") }} {{readonlyInline}}</dt> + <dd>Returns a unique identifier for this <code>Touch</code> object. A given touch point (say, by a finger) will have the same identifier for the duration of its movement around the surface. This lets you ensure that you're tracking the same touch all the time.</dd> + <dt><strong>{{ domxref("Touch.screenX") }} </strong>{{readonlyInline}}</dt> + <dd>Returns the X coordinate of the touch point relative to the left edge of the screen.</dd> + <dt><strong>{{ domxref("Touch.screenY") }} </strong>{{readonlyInline}}</dt> + <dd>Returns the Y coordinate of the touch point relative to the top edge of the screen.</dd> + <dt><strong>{{ domxref("Touch.clientX") }} </strong>{{readonlyInline}}</dt> + <dd>Returns the X coordinate of the touch point relative to the left edge of the browser viewport, not including any scroll offset.</dd> + <dt><strong>{{ domxref("Touch.clientY") }} </strong>{{readonlyInline}}</dt> + <dd>Returns the Y coordinate of the touch point relative to the top edge of the browser viewport, not including any scroll offset.</dd> + <dt>{{ domxref("Touch.pageX") }} {{readonlyInline}}</dt> + <dd>Returns the X coordinate of the touch point relative to the left edge of the document. Unlike <code>clientX</code>, this value includes the horizontal scroll offset, if any.</dd> + <dt>{{ domxref("Touch.pageY") }} {{readonlyInline}}</dt> + <dd>Returns the Y coordinate of the touch point relative to the top of the document. Unlike <code>clientY,</code> this value includes the vertical scroll offset, if any.</dd> + <dt>{{ domxref("Touch.target") }} {{readonlyInline}}</dt> + <dd>Returns the {{ domxref("Element")}} on which the touch point started when it was first placed on the surface, even if the touch point has since moved outside the interactive area of that element or even been removed from the document.</dd> +</dl> + +<h3 id="觸碰區（Touch_area）">觸碰區（Touch area）</h3> + +<p>{{SeeCompatTable}}</p> + +<dl> + <dt>{{ domxref("Touch.radiusX") }} {{readonlyInline}} {{experimental_inline}}</dt> + <dd>Returns the X radius of the ellipse that most closely circumscribes the area of contact with the screen. The value is in pixels of the same scale as <code>screenX</code>.</dd> + <dt>{{ domxref("Touch.radiusY") }} {{readonlyInline}} {{experimental_inline}}</dt> + <dd>Returns the Y radius of the ellipse that most closely circumscribes the area of contact with the screen. The value is in pixels of the same scale as <code>screenY</code>.</dd> + <dt>{{ domxref("Touch.rotationAngle") }} {{readonlyInline}} {{experimental_inline}}</dt> + <dd>Returns the angle (in degrees) that the ellipse described by radiusX and radiusY must be rotated, clockwise, to most accurately cover the area of contact between the user and the surface.</dd> + <dt>{{ domxref("Touch.force") }}{{readonlyInline}} {{experimental_inline}}</dt> + <dd>Returns the amount of pressure being applied to the surface by the user, as a <code>float</code> between <code>0.0</code> (no pressure) and <code>1.0</code> (maximum pressure).</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>This interface has no method and no parent, and doesn't inherits or implements any method.</em></p> + +<dl> +</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('Touch Events 2', '#touch-interface', 'Touch')}}</td> + <td>{{Spec2('Touch Events 2')}}</td> + <td>Added <code>radiusX</code>, <code>radiusY</code>, <code>rotationAngle</code>, <code>force</code> properties, as well as the <code>Touch()</code> constructor.</td> + </tr> + <tr> + <td>{{SpecName('Touch Events', '#touch-interface', 'Touch')}}</td> + <td>{{Spec2('Touch Events')}}</td> + <td>Initial definition.</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatChrome("22.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("18.0")}}<sup>[1]</sup><br> + {{CompatGeckoDesktop("52.0")}}<sup>[2]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>radiusX</code>, <code>radiusY</code>, <code>rotationAngle</code>, <code>force</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>Touch()</code> constructor</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</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>Chrome for Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("6.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>11</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>radiusX</code>, <code>radiusY</code>, <code>rotationAngle</code>, <code>force</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("6.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>Touch()</code> constructor</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Touch events were implemented in Gecko 18.0, but removed again in 24.0 {{geckoRelease("24.0")}} on the desktop version of Firefox due to web compatibility issues ({{bug(888304)}}).</p> + +<p>[2] As of Gecko 52.0, touch events support has been fixed and reenabled in Windows desktop platforms.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("Touch_events","Touch Events Overview")}}</li> + <li>{{ domxref("Document.createTouch()") }}</li> +</ul> + +<dl> +</dl> diff --git a/files/zh-tw/web/api/touch_events/index.html b/files/zh-tw/web/api/touch_events/index.html new file mode 100644 index 0000000000..c12a14f49c --- /dev/null +++ b/files/zh-tw/web/api/touch_events/index.html @@ -0,0 +1,387 @@ +--- +title: 觸控事件 +slug: Web/API/Touch_events +translation_of: Web/API/Touch_events +--- +<div>{{DefaultAPISidebar("Touch Events")}}</div> + +<p>為了支援基於觸碰的使用者介面，觸控事件提供了解釋手指或觸控筆於觸控螢幕或觸控板上活動的資訊。</p> + +<p>觸控事件介面為相對低階的 API，可用來支援應用程式特定的多點觸控互動，例如兩指手勢。多點觸控互動起始於手指或觸控筆於平面的第一個觸碰，其它的手指可能於其後伴隨著移動才觸碰到平面。而互動則結束於手指自觸控平面離開。在此互動期間，應用程式會於開始、移動以及結束的階段接收到觸控事件。</p> + +<p>觸控事件類似於滑鼠事件，但觸控事件支援同時間多個觸碰及其於觸控平面的每個不同點位置。{{domxref("TouchEvent")}} 介面封裝了所有當前作用中的觸碰點。{{domxref("Touch")}} 介面則表示個別的觸碰點，包括了如觸碰點於瀏覽器 viewport 中的相對位置資訊。</p> + +<h2 id="定義">定義</h2> + +<dl> + <dt>平面（Surface）</dt> + <dd>The touch-sensitive surface. This may be a screen or trackpad.</dd> +</dl> + +<dl> + <dt>觸碰點（Touch point）</dt> + <dd>A point of contact with the surface. This may be a finger (or elbow, ear, nose, whatever, but typically a finger) or stylus.</dd> +</dl> + +<h2 id="介面">介面</h2> + +<dl> + <dt>{{domxref("TouchEvent")}}</dt> + <dd>Represents an event that occurs when the state of touches on the surface changes.</dd> + <dt>{{domxref("Touch")}}</dt> + <dd>Represents a single point of contact between the user and the touch surface.</dd> + <dt>{{domxref("TouchList")}}</dt> + <dd>Represents a group of touches; this is used when the user has, for example, multiple fingers on the surface at the same time.</dd> +</dl> + +<h2 id="範例">範例</h2> + +<p>This example tracks multiple touch points at a time, allowing the user to draw in a {{HTMLElement("canvas")}} with more than one finger at a time. It will only work on a browser that supports touch events.</p> + +<div class="note"><strong>Note:</strong> The text below uses the term "finger" when describing the contact with the surface, but it could, of course, also be a stylus or other contact method.</div> + +<h3 id="Create_a_canvas">Create a canvas</h3> + +<pre class="brush: html"><canvas id="canvas" width="600" height="600" style="border:solid black 1px;"> + Your browser does not support canvas element. +</canvas> +<br> +<button onclick="startup()">Initialize</button> +<br> +Log: <pre id="log" style="border: 1px solid #ccc;"></pre> +</pre> + +<h3 id="Setting_up_the_event_handlers">Setting up the event handlers</h3> + +<p>When the page loads, the <code>startup()</code> function shown below should be called by our {{HTMLElement("body")}} element's <code>onload</code> attribute (but in the example we use a button to trigger it, due to limitations of the MDN live example system).</p> + +<pre class="brush: js">function startup() { + var el = document.getElementsByTagName("canvas")[0]; + el.addEventListener("touchstart", handleStart, false); + el.addEventListener("touchend", handleEnd, false); + el.addEventListener("touchcancel", handleCancel, false); + el.addEventListener("touchmove", handleMove, false); + log("initialized."); +} +</pre> + +<p>This simply sets up all the event listeners for our {{HTMLElement("canvas")}} element so we can handle the touch events as they occur.</p> + +<h4 id="Tracking_new_touches">Tracking new touches</h4> + +<p>We'll keep track of the touches in-progress.</p> + +<pre class="brush: js">var ongoingTouches = []; +</pre> + +<p>When a {{event("touchstart")}} event occurs, indicating that a new touch on the surface has occurred, the <code>handleStart()</code> function below is called.</p> + +<pre class="brush: js">function handleStart(evt) { + evt.preventDefault(); + log("touchstart."); + var el = document.getElementsByTagName("canvas")[0]; + var ctx = el.getContext("2d"); + var touches = evt.changedTouches; + + for (var i = 0; i < touches.length; i++) { + log("touchstart:" + i + "..."); + ongoingTouches.push(copyTouch(touches[i])); + var color = colorForTouch(touches[i]); + ctx.beginPath(); + ctx.arc(touches[i].pageX, touches[i].pageY, 4, 0, 2 * Math.PI, false); // a circle at the start + ctx.fillStyle = color; + ctx.fill(); + log("touchstart:" + i + "."); + } +} +</pre> + +<p>This calls {{domxref("event.preventDefault()")}} to keep the browser from continuing to process the touch event (this also prevents a mouse event from also being delivered). Then we get the context and pull the list of changed touch points out of the event's {{domxref("TouchEvent.changedTouches")}} property.</p> + +<p>After that, we iterate over all the {{domxref("Touch")}} objects in the list, pushing them onto an array of active touch points and drawing the start point for the draw as a small circle; we're using a 4-pixel wide line, so a 4 pixel radius circle will show up neatly.</p> + +<h4 id="Drawing_as_the_touches_move">Drawing as the touches move</h4> + +<p>Each time one or more fingers moves, a {{event("touchmove")}} event is delivered, resulting in our <code>handleMove()</code> function being called. Its responsibility in this example is to update the cached touch information and to draw a line from the previous position to the current position of each touch.</p> + +<pre class="brush: js">function handleMove(evt) { + evt.preventDefault(); + var el = document.getElementsByTagName("canvas")[0]; + var ctx = el.getContext("2d"); + var touches = evt.changedTouches; + + for (var i = 0; i < touches.length; i++) { + var color = colorForTouch(touches[i]); + var idx = ongoingTouchIndexById(touches[i].identifier); + + if (idx >= 0) { + log("continuing touch "+idx); + ctx.beginPath(); + log("ctx.moveTo(" + ongoingTouches[idx].pageX + ", " + ongoingTouches[idx].pageY + ");"); + ctx.moveTo(ongoingTouches[idx].pageX, ongoingTouches[idx].pageY); + log("ctx.lineTo(" + touches[i].pageX + ", " + touches[i].pageY + ");"); + ctx.lineTo(touches[i].pageX, touches[i].pageY); + ctx.lineWidth = 4; + ctx.strokeStyle = color; + ctx.stroke(); + + ongoingTouches.splice(idx, 1, copyTouch(touches[i])); // swap in the new touch record + log("."); + } else { + log("can't figure out which touch to continue"); + } + } +} +</pre> + +<p>This iterates over the changed touches as well, but it looks in our cached touch information array for the previous information about each touch in order to determine the starting point for each touch's new line segment to be drawn. This is done by looking at each touch's {{domxref("Touch.identifier")}} property. This property is a unique integer for each touch, and remains consistent for each event during the duration of each finger's contact with the surface.</p> + +<p>This lets us get the coordinates of the previous position of each touch and use the appropriate context methods to draw a line segment joining the two positions together.</p> + +<p>After drawing the line, we call <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice"><code>Array.splice()</code></a> to replace the previous information about the touch point with the current information in the <code>ongoingTouches</code> array.</p> + +<h4 id="Handling_the_end_of_a_touch">Handling the end of a touch</h4> + +<p>When the user lifts a finger off the surface, a {{event("touchend")}} event is sent. We handle both of these the same way: by calling the <code>handleEnd()</code> function below. Its job is to draw the last line segment for each touch that ended and remove the touch point from the ongoing touch list.</p> + +<pre class="brush: js">function handleEnd(evt) { + evt.preventDefault(); + log("touchend"); + var el = document.getElementsByTagName("canvas")[0]; + var ctx = el.getContext("2d"); + var touches = evt.changedTouches; + + for (var i = 0; i < touches.length; i++) { + var color = colorForTouch(touches[i]); + var idx = ongoingTouchIndexById(touches[i].identifier); + + if (idx >= 0) { + ctx.lineWidth = 4; + ctx.fillStyle = color; + ctx.beginPath(); + ctx.moveTo(ongoingTouches[idx].pageX, ongoingTouches[idx].pageY); + ctx.lineTo(touches[i].pageX, touches[i].pageY); + ctx.fillRect(touches[i].pageX - 4, touches[i].pageY - 4, 8, 8); // and a square at the end + ongoingTouches.splice(idx, 1); // remove it; we're done + } else { + log("can't figure out which touch to end"); + } + } +} +</pre> + +<p>This is very similar to the previous function; the only real differences are that we draw a small square to mark the end and that when we call <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice"><code>Array.splice()</code></a>, we simply remove the old entry from the ongoing touch list, without adding in the updated information. The result is that we stop tracking that touch point.</p> + +<h4 id="Handling_canceled_touches">Handling canceled touches</h4> + +<p>If the user's finger wanders into browser UI, or the touch otherwise needs to be canceled, the {{event("touchcancel")}} event is sent, and we call the <code>handleCancel()</code> function below.</p> + +<pre class="brush: js">function handleCancel(evt) { + evt.preventDefault(); + log("touchcancel."); + var touches = evt.changedTouches; + + for (var i = 0; i < touches.length; i++) { + var idx = ongoingTouchIndexById(touches[i].identifier); + ongoingTouches.splice(idx, 1); // remove it; we're done + } +} +</pre> + +<p>Since the idea is to immediately abort the touch, we simply remove it from the ongoing touch list without drawing a final line segment.</p> + +<h3 id="Convenience_functions">Convenience functions</h3> + +<p>This example uses two convenience functions that should be looked at briefly to help make the rest of the code more clear.</p> + +<h4 id="Selecting_a_color_for_each_touch">Selecting a color for each touch</h4> + +<p>In order to make each touch's drawing look different, the <code>colorForTouch()</code> function is used to pick a color based on the touch's unique identifier. This identifier is an opaque number, but we can at least rely on it differing between the currently-active touches.</p> + +<pre class="brush: js">function colorForTouch(touch) { + var r = touch.identifier % 16; + var g = Math.floor(touch.identifier / 3) % 16; + var b = Math.floor(touch.identifier / 7) % 16; + r = r.toString(16); // make it a hex digit + g = g.toString(16); // make it a hex digit + b = b.toString(16); // make it a hex digit + var color = "#" + r + g + b; + log("color for touch with identifier " + touch.identifier + " = " + color); + return color; +} +</pre> + +<p>The result from this function is a string that can be used when calling {{HTMLElement("canvas")}} functions to set drawing colors. For example, for a {{domxref("Touch.identifier")}} value of 10, the resulting string is "#aaa".</p> + +<h4 id="Copying_a_touch_object">Copying a touch object</h4> + +<p>Some browsers (mobile Safari, for one) re-use touch objects between events, so it's best to copy the bits you care about, rather than referencing the entire object.</p> + +<pre class="brush: js">function copyTouch(touch) { + return { identifier: touch.identifier, pageX: touch.pageX, pageY: touch.pageY }; +}</pre> + +<h4 id="Finding_an_ongoing_touch">Finding an ongoing touch</h4> + +<p>The <code>ongoingTouchIndexById()</code> function below scans through the <code>ongoingTouches</code> array to find the touch matching the given identifier, then returns that touch's index into the array.</p> + +<pre class="brush: js">function ongoingTouchIndexById(idToFind) { + for (var i = 0; i < ongoingTouches.length; i++) { + var id = ongoingTouches[i].identifier; + + if (id == idToFind) { + return i; + } + } + return -1; // not found +} +</pre> + +<h4 id="Showing_what's_going_on">Showing what's going on</h4> + +<pre class="brush: js">function log(msg) { + var p = document.getElementById('log'); + p.innerHTML = msg + "\n" + p.innerHTML; +}</pre> + +<p>If your browser supports it, you can {{LiveSampleLink('Example', 'see it live')}}.</p> + +<p><a href="http://jsfiddle.net/Darbicus/z3Xdx/10/">jsFiddle example</a></p> + +<h2 id="Additional_tips">Additional tips</h2> + +<p>This section provides additional tips on how to handle touch events in your web application.</p> + +<h3 id="Handling_clicks">Handling clicks</h3> + +<p>Since calling <code>preventDefault()</code> on a {{event("touchstart")}} or the first {{event("touchmove")}} event of a series prevents the corresponding mouse events from firing, it's common to call <code>preventDefault()</code> on {{event("touchmove")}} rather than {{event("touchstart")}}. That way, mouse events can still fire and things like links will continue to work. Alternatively, some frameworks have taken to refiring touch events as mouse events for this same purpose. (This example is oversimplified and may result in strange behavior. It is only intended as a guide.)</p> + +<pre class="brush: js">function onTouch(evt) { + evt.preventDefault(); + if (evt.touches.length > 1 || (evt.type == "touchend" && evt.touches.length > 0)) + return; + + var newEvt = document.createEvent("MouseEvents"); + var type = null; + var touch = null; + + switch (evt.type) { + case "touchstart": + type = "mousedown"; + touch = evt.changedTouches[0]; + break; + case "touchmove": + type = "mousemove"; + touch = evt.changedTouches[0]; + break; + case "touchend": + type = "mouseup"; + touch = evt.changedTouches[0]; + break; + } + + newEvt.initMouseEvent(type, true, true, evt.originalTarget.ownerDocument.defaultView, 0, + touch.screenX, touch.screenY, touch.clientX, touch.clientY, + evt.ctrlKey, evt.altKey, evt.shiftKey, evt.metaKey, 0, null); + evt.originalTarget.dispatchEvent(newEvt); +} +</pre> + +<h3 id="Calling_preventDefault()_only_on_a_second_touch">Calling preventDefault() only on a second touch</h3> + +<p>One technique for preventing things like <code>pinchZoom</code> on a page is to call <code>preventDefault()</code> on the second touch in a series. This behavior is not well defined in the touch events spec, and results in different behavior for different browsers (i.e., iOS will prevent zooming but still allow panning with both fingers; Android will allow zooming but not panning; Opera and Firefox currently prevent all panning and zooming.) Currently, it's not recommended to depend on any particular behavior in this case, but rather to depend on meta viewport to prevent zooming.</p> + +<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('Touch Events 2', '#touch-interface', 'Touch')}}</td> + <td>{{Spec2('Touch Events 2')}}</td> + <td>Added <code>radiusX</code>, <code>radiusY</code>, <code>rotationAngle</code>, <code>force</code> properties</td> + </tr> + <tr> + <td>{{SpecName('Touch Events', '#touch-interface', 'Touch')}}</td> + <td>{{Spec2('Touch Events')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<p>Note that unfortunately touch events may not fire at all on laptops with touch functionality (<a href="/en-US/docs/">test page</a>).</p> + +<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("22.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("18.0")}}<sup>[1]</sup><br> + {{CompatGeckoDesktop("52.0")}}<sup>[2]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</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>Chrome for Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("6.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>11</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] The <code>dom.w3c_touch_events.enabled</code> tri-state preference can be used to disable (0), enable (1), and auto-detect (2) support for standard touch events; by default, they're on auto-detect (2).</p> + +<p>As of Gecko 24.0 {{geckoRelease("24.0")}}, the touch events support introduced with Gecko 18.0 {{geckoRelease("18.0")}} has been disabled on the desktop version of Firefox ({{bug(888304)}}), as some popular sites including Google and Twitter were not working properly. Once the bug is fixed, the API will be enabled again. To enable it anyway, open <code>about:config</code> and set the <code>dom.w3c_touch_events.enabled</code> preference to <code>2</code>. The mobile versions including <a href="/en-US/docs/Mozilla/Firefox_for_Android">Firefox for Android</a> and <a href="/en-US/docs/Mozilla/Firefox_OS">Firefox OS</a> are not affected by this change.</p> + +<p>[2] As of Gecko 52.0, touch events support has been fixed and reenabled in Windows desktop platforms.</p> + +<div class="note"> +<p><strong>Note</strong>: Prior to Gecko 6.0 {{geckoRelease("6.0")}}, Gecko offered a <a href="/en-US/docs/Web/Guide/Events/Touch_events_(Mozilla_experimental)">proprietary touch event API</a>. That API is now deprecated; you should switch to this one.</p> +</div> diff --git a/files/zh-tw/web/api/touchevent/index.html b/files/zh-tw/web/api/touchevent/index.html new file mode 100644 index 0000000000..5c435c008f --- /dev/null +++ b/files/zh-tw/web/api/touchevent/index.html @@ -0,0 +1,201 @@ +--- +title: TouchEvent +slug: Web/API/TouchEvent +translation_of: Web/API/TouchEvent +--- +<p>{{ APIRef("Touch Events") }}</p> + +<p><strong><code>TouchEvent</code></strong> 介面表示了一個由觸控平面因觸碰而改變狀態所發出的事件。平面可以是觸控螢幕或是觸控板，<code>TouchEvent</code> 能描述一或多個觸碰點，並且支援偵測其移動、增加或減少觸碰點等等功能。</p> + +<p>觸碰點是由 {{ domxref("Touch") }} 物件表示；每一個觸碰點描述了其位置、大小與形狀、壓力值以及目標元素。觸碰點列表由 {{ domxref("TouchList") }} 所表示。</p> + +<h2 id="建構式">建構式</h2> + +<dl> + <dt>{{domxref("TouchEvent.TouchEvent", "TouchEvent()")}}</dt> + <dd>Creates a <code>TouchEvent</code> object.</dd> +</dl> + +<h2 id="屬性">屬性</h2> + +<p><em>此介面也繼承了其父介面 {{domxref("UIEvent")}} 與 {{domxref("Event")}} 的屬性</em></p> + +<dl> + <dt>{{ domxref("TouchEvent.altKey") }} {{readonlyInline}}</dt> + <dd>A Boolean value indicating whether or not the alt key was down when the touch event was fired.</dd> + <dt>{{ domxref("TouchEvent.changedTouches") }} {{readonlyInline}}</dt> + <dd>A {{ domxref("TouchList") }} of all the {{ domxref("Touch") }} objects representing individual points of contact whose states changed between the previous touch event and this one.</dd> + <dt>{{ domxref("TouchEvent.ctrlKey") }} {{readonlyInline}}</dt> + <dd>A Boolean value indicating whether or not the control key was down when the touch event was fired.</dd> + <dt>{{ domxref("TouchEvent.metaKey") }} {{readonlyInline}}</dt> + <dd>A Boolean value indicating whether or not the meta key was down when the touch event was fired.</dd> + <dt>{{ domxref("TouchEvent.shiftKey") }} {{readonlyInline}}</dt> + <dd>A Boolean value indicating whether or not the shift key was down when the touch event was fired.</dd> + <dt>{{ domxref("TouchEvent.targetTouches") }}{{readonlyInline}}</dt> + <dd>A {{ domxref("TouchList") }} of all the {{ domxref("Touch") }} objects that are both currently in contact with the touch surface <strong>and</strong> were also started on the same element that is the target of the event.</dd> + <dt>{{ domxref("TouchEvent.touches") }} {{readonlyInline}}</dt> + <dd>A {{ domxref("TouchList") }} of all the {{ domxref("Touch") }} objects representing all current points of contact with the surface, regardless of target or changed status.</dd> +</dl> + +<h2 id="觸控事件類型">觸控事件類型</h2> + +<p>觸控事件有多個種類可以代表觸碰狀態發生了改變。可以藉由 {{ domxref("event.type", "TouchEvent.type") }} 屬性來確認是哪一個種類的觸控事件。</p> + +<h3 id="event(touchstart)">{{event("touchstart")}}</h3> + +<p>Sent when the user places a touch point on the touch surface. The event's target will be the {{ domxref("element") }} in which the touch occurred.</p> + +<h3 id="event(touchend)">{{event("touchend")}}</h3> + +<p>Sent when the user removes a touch point from the surface (that is, when they lift a finger or stylus from the surface). This is also sent if the touch point moves off the edge of the surface; for example, if the user's finger slides off the edge of the screen.</p> + +<p>The event's target is the same {{ domxref("element") }} that received the <code>touchstart</code> event corresponding to the touch point, even if the touch point has moved outside that element.</p> + +<p>The touch point (or points) that were removed from the surface can be found in the {{ domxref("TouchList") }} specified by the <code>changedTouches</code> attribute.</p> + +<h3 id="event(touchmove)">{{event("touchmove")}}</h3> + +<p>Sent when the user moves a touch point along the surface. The event's target is the same {{ domxref("element") }} that received the <code>touchstart</code> event corresponding to the touch point, even if the touch point has moved outside that element.</p> + +<p>This event is also sent if the values of the radius, rotation angle, or force attributes of a touch point change.</p> + +<div class="note"><strong>Note:</strong> The rate at which <code>touchmove</code> events is sent is browser-specific, and may also vary depending on the capability of the user's hardware. You must not rely on a specific granularity of these events.</div> + +<h3 id="event(touchcancel)">{{event("touchcancel")}}</h3> + +<p>Sent when a touch point has been disrupted in some way. There are several possible reasons why this might happen (and the exact reasons will vary from device to device, as well as browser to browser):</p> + +<ul> + <li>An event of some kind occurred that canceled the touch; this might happen if a modal alert pops up during the interaction.</li> + <li>The touch point has left the document window and moved into the browser's UI area, a plug-in, or other external content.</li> + <li>The user has placed more touch points on the screen than can be supported, in which case the earliest {{ domxref("Touch") }} in the {{ domxref("TouchList") }} gets canceled.</li> +</ul> + +<h3 id="Using_with_addEventListener()_and_preventDefault()">Using with addEventListener() and preventDefault()</h3> + +<p>It's important to note that in many cases, both touch and mouse events get sent (in order to let non-touch-specific code still interact with the user). If you use touch events, you should call {{domxref("Event.preventDefault","preventDefault()")}} to keep the mouse event from being sent as well.</p> + +<p>The exception to this is Chrome, starting with version 56 (desktop, Chrome for android, and android webview), where the default value for {{event("touchstart")}} and {{event("touchmove")}} is <code>true</code> and calls to {{domxref("Event.preventDefault","preventDefault()")}} are not needed. To override this behavior, you simply set the <code>passive</code> option to <code>false</code> as shown in the example below. This change prevents the listener from blocking page rendering while a user is scrolling. A demo is available on the <a href="https://developers.google.com/web/updates/2016/06/passive-event-listeners">Google Developer</a> site.</p> + +<h2 id="GlobalEventHandlers">GlobalEventHandlers</h2> + +<p>{{SeeCompatTable}}</p> + +<dl> + <dt>{{ domxref("GlobalEventHandlers.ontouchstart") }} {{experimental_inline}}</dt> + <dd>A {{domxref("GlobalEventHandlers","global event handler")}} for the {{event("touchstart")}} event.</dd> + <dt>{{ domxref("GlobalEventHandlers.ontouchend") }} {{experimental_inline}}</dt> + <dd>A {{domxref("GlobalEventHandlers","global event handler")}} for the {{event("touchend")}} event.</dd> + <dt>{{ domxref("GlobalEventHandlers.ontouchmove") }} {{experimental_inline}}</dt> + <dd>A {{domxref("GlobalEventHandlers","global event handler")}} for the {{event("touchmove")}} event.</dd> + <dt>{{ domxref("GlobalEventHandlers.ontouchcancel") }} {{experimental_inline}}</dt> + <dd>A {{domxref("GlobalEventHandlers","global event handler")}} for the {{event("touchcancel")}} event.</dd> +</dl> + +<h2 id="範例">範例</h2> + +<p>See the <a href="/en/DOM/Touch_events#Example" title="en/DOM/Touch events#Example">example on the main Touch events article</a>.</p> + +<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('Touch Events 2','#touchevent-interface', 'TouchEvent')}}</td> + <td>{{Spec2('Touch Events 2')}}</td> + <td>Added <code>ontouchstart</code>, <code>ontouchend</code>, <code>ontouchmove</code>, <code>ontouchend</code> global attribute handlers</td> + </tr> + <tr> + <td>{{SpecName('Touch Events', '#touchevent-interface', 'TouchEvent')}}</td> + <td>{{Spec2('Touch Events')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatChrome("22.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("18.0")}}<sup>[1]</sup><br> + {{CompatGeckoDesktop("52.0")}}<sup>[2]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android Webview</th> + <th>Chrome for Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("6.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>11</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>TouchEvent()</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Touch events were implemented in Gecko 18.0, but removed again in 24.0 {{geckoRelease("24.0")}} on the desktop version of Firefox due to web compatibility issues ({{bug(888304)}}).</p> + +<p>[2] As of Gecko 52.0, touch events support has been fixed and reenabled in Windows desktop platforms.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("Touch_events","Touch Events Overview")}}</li> + <li>{{domxref("GestureEvent")}}</li> + <li>{{domxref("MSGestureEvent")}}</li> +</ul> diff --git a/files/zh-tw/web/api/touchlist/index.html b/files/zh-tw/web/api/touchlist/index.html new file mode 100644 index 0000000000..d106b9df7d --- /dev/null +++ b/files/zh-tw/web/api/touchlist/index.html @@ -0,0 +1,120 @@ +--- +title: TouchList +slug: Web/API/TouchList +translation_of: Web/API/TouchList +--- +<div> +<p>{{ APIRef("Touch Events") }}</p> +</div> + +<p><code>TouchList</code> 介面表示了一個觸控平面上所有觸碰點的列表；舉例來說，假如使用者有三隻手指於觸控平面（如觸控螢幕或是觸控板）上，則其相對應的 <code>TouchList</code> 物件中就會分別有三個 {{domxref("Touch")}} 物件各代表一個手指的觸碰。</p> + +<h2 id="屬性">屬性</h2> + +<dl> + <dt>{{domxref("TouchList.length")}} {{readonlyInline}}</dt> + <dd>The number of {{domxref("Touch")}} objects in the <code>TouchList</code>.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<dl> + <dt>{{domxref("TouchList.identifiedTouch()")}} {{obsolete_inline}}</dt> + <dd>Returns the first {{domxref("Touch")}} item in the list whose identifier matches a specified value.</dd> + <dt>{{domxref("TouchList.item()")}}</dt> + <dd>Returns the {{domxref("Touch")}} object at the specified index in the list.</dd> +</dl> + +<h2 id="範例">範例</h2> + +<p>See the <a href="/en-US/docs/DOM/Touch_events#Example" title="DOM/Touch events#Example">example on the main Touch events article</a>.</p> + +<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('Touch Events 2','#touchlist-interface')}}</td> + <td>{{Spec2('Touch Events 2')}}</td> + <td>Non-stable version.</td> + </tr> + <tr> + <td>{{SpecName('Touch Events', '#touchlist-interface')}}</td> + <td>{{Spec2('Touch Events')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatChrome("22.0")}}</td> + <td>{{CompatGeckoDesktop("18.0")}}<sup>[1]</sup><br> + {{CompatGeckoDesktop("52.0")}}<sup>[2]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</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>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("6.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>11</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Touch events were implemented in Gecko 18.0, but removed again in 24.0 {{geckoRelease("24.0")}} on the desktop version of Firefox due to web compatibility issues ({{bug(888304)}}).</p> + +<p>[2] As of Gecko 52.0, touch events support has been fixed and reenabled in Windows desktop platforms.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/en-US/docs/DOM/Touch_events" title="DOM/Touch events">Touch events</a></li> + <li>{{domxref("Document.createTouchList()")}}</li> +</ul> diff --git a/files/zh-tw/web/api/uievent/index.html b/files/zh-tw/web/api/uievent/index.html new file mode 100644 index 0000000000..a5a1228ec8 --- /dev/null +++ b/files/zh-tw/web/api/uievent/index.html @@ -0,0 +1,188 @@ +--- +title: UIEvent +slug: Web/API/UIEvent +tags: + - 待翻譯 +translation_of: Web/API/UIEvent +--- +<p>{{APIRef("DOM Events")}}</p> + +<p><strong><code>UIEvent</code></strong> 介面是使用者介面的事件的基本型態。</p> + +<p><code>UIEvent</code> 是從 {{domxref("Event")}} 衍伸過來。 雖然為了相容性，仍留著 {{domxref("UIEvent.initUIEvent()")}} 方法，建立 <code>UIEvent</code> 物件最好是選擇以 {{domxref("UIEvent.UIEvent", "UIEvent()")}} constructor 建立。</p> + +<p>許多介面直接或間接繼承此介面，例如：{{domxref("MouseEvent")}}、{{domxref("TouchEvent")}}、{{domxref("FocusEvent")}}、{{domxref("KeyboardEvent")}}、{{domxref("WheelEvent")}}、{{domxref("InputEvent")}} 和 {{domxref("CompositionEvent")}}。</p> + +<h2 id="建構式">建構式</h2> + +<dl> + <dt>{{domxref("UIEvent.UIEvent()", "UIEvent()")}}</dt> + <dd>建立一個 <code>UIEvent</code> 物件 。</dd> +</dl> + +<h2 id="屬性">屬性</h2> + +<p><em>此介面亦繼承其父－－ {{domxref("Event")}} 的屬性：</em></p> + +<dl> + <dt>{{domxref("UIEvent.cancelBubble")}} {{Non-standard_inline}} {{Deprecated_inline}}</dt> + <dd>Is a {{jsxref("Boolean")}} indicating whether the bubbling of the event has been canceled or not.</dd> +</dl> + +<dl> + <dt>{{domxref("UIEvent.detail")}}{{readonlyinline}}</dt> + <dd>Returns a <code>long</code> with details about the event, depending on the event type.</dd> + <dt>{{domxref("UIEvent.isChar")}} {{obsolete_inline}} {{readonlyinline}}</dt> + <dd>Returns a {{jsxref("Boolean")}} indicating whether the event produced a key character or not.</dd> + <dt>{{domxref("UIEvent.layerX")}} {{Non-standard_inline}} {{readonlyinline}}</dt> + <dd>Returns the horizontal coordinate of the event relative to the current layer.</dd> + <dt>{{domxref("UIEvent.layerY")}} {{Non-standard_inline}} {{readonlyinline}}</dt> + <dd>Returns the vertical coordinate of the event relative to the current layer.</dd> + <dt>{{domxref("UIEvent.pageX")}} {{Non-standard_inline}} {{readonlyinline}}</dt> + <dd>Returns the horizontal coordinate of the event relative to the whole document.</dd> + <dt>{{domxref("UIEvent.pageY")}} {{Non-standard_inline}} {{readonlyinline}}</dt> + <dd>Returns the vertical coordinate of the event relative to the whole document.</dd> + <dt>{{domxref("UIEvent.sourceCapabilities")}} {{non-standard_inline}} {{readonlyinline}}</dt> + <dd>Returns an instance of the InputDeviceCapabilities interface which provides information about the physical device responsible for generating a touch event.</dd> + <dt>{{domxref("UIEvent.view")}}{{readonlyinline}}</dt> + <dd>Returns a {{domxref("WindowProxy")}} that contains the view that generated the event.</dd> + <dt>{{domxref("UIEvent.which")}} {{Non-standard_inline}} {{readonlyinline}}</dt> + <dd>Returns the numeric <code>keyCode</code> of the key pressed, or the character code (<code>charCode</code>) for an alphanumeric key pressed.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>此介面亦繼承其父－－ {{domxref("Event")}} 的方法：</em></p> + +<dl> + <dt>{{domxref("UIEvent.initUIEvent()")}} {{deprecated_inline}}</dt> + <dd>初始化 <code>UIEvent</code> 物件。若該事件已經觸發的話，此方法就不會執行任何東西。</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('InputDeviceCapabilities')}}</td> + <td>{{Spec2('InputDeviceCapabilities')}}</td> + <td>Added <code>sourceCapabilities</code> property.</td> + </tr> + <tr> + <td>{{SpecName('DOM3 Events', '#interface-UIEvent', 'UIEvent')}}</td> + <td>{{Spec2('DOM3 Events')}}</td> + <td>Added the <code>UIEvent()</code> constructor, deprecated the <code>initUIEvent()</code> method and changed the type of <code>view</code> from <code>AbstractView</code> to <code>WindowProxy</code>.</td> + </tr> + <tr> + <td>{{SpecName('DOM2 Events', '#Events-UIEvent', 'UIEvent')}}</td> + <td>{{Spec2('DOM2 Events')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility" name="Browser_compatibility">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}<sup>[2]</sup></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>UIEvent()</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(11)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>cancelBubble</code> defined on Event</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(53)}}<sup>[1]</sup></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}<sup>[2]</sup></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>UIEvent()</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile(11)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>cancelBubble</code> defined on Event</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile(53)}}<sup>[1]</sup></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] From Firefox 52, this property is now defined on the {{domxref("Event")}} interface instead. See {{bug(1298970)}} for more details.</p> + +<p>[2] The {{domxref("UIEvent.isChar", "isChar")}} property has never been supported by any browser but Firefox, and even on Firefox it's never worked except on Mac OSX. For that reason, it's been removed in Firefox 55 to align with other browsers.</p> + +<h2 class="editable" id="參見"><span>參見</span></h2> + +<ul> + <li><a href="/en-US/docs/Learn/JavaScript/Building_blocks/Events">Introduction to events</a></li> + <li>{{domxref("Event")}}</li> +</ul> diff --git a/files/zh-tw/web/api/uievent/uievent/index.html b/files/zh-tw/web/api/uievent/uievent/index.html new file mode 100644 index 0000000000..d18be6387f --- /dev/null +++ b/files/zh-tw/web/api/uievent/uievent/index.html @@ -0,0 +1,134 @@ +--- +title: UIEvent() +slug: Web/API/UIEvent/UIEvent +translation_of: Web/API/UIEvent/UIEvent +--- +<p>{{APIRef("DOM Events")}}</p> + +<p><strong><code>UIEvent()</code></strong> constructor 是用來建立新的 {{domxref("UIEvent")}}。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"> <em>event</em> = new UIEvent(<em>typeArg</em>, <em>UIEventInit</em>);</pre> + +<h3 id="參數">參數</h3> + +<dl> + <dt><em>typeArg</em></dt> + <dd>一個 {{domxref("DOMString")}} ，用來表示事件名稱</dd> + <dt><em>UIEventInit</em>{{optional_inline}}</dt> +</dl> + +<dl> + <dd>一個 <code>UIEventInit</code> dictionary ，能接受以下參數： + + <table class="standard-table"> + <thead> + <tr> + <th>參數</th> + <th>可選</th> + <th>默認值</th> + <th>類型</th> + <th>說明</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>"detail"</code></td> + <td>●</td> + <td><code>0</code></td> + <td><code>long</code></td> + <td>定義事件意義的值。關於事件的意義於 {{domxref("UIEvent.detail")}} 已有較詳盡的列表。</td> + </tr> + <tr> + <td><code>"view"</code></td> + <td>●</td> + <td><code>null</code></td> + <td>{{domxref("WindowProxy")}}</td> + <td>與事件相關的 {{domxref("Window")}} 。</td> + </tr> + </tbody> + </table> + + <div class="note"> + <p><em><code>UIEventInit</code> dictionary 亦接受 {{domxref("Event.Event", "EventInit")}} dictionary 所接受的參數。</em></p> + </div> + </dd> +</dl> + +<h2 id="Specifications" name="Specifications">規格</h2> + +<table class="standard-table" style="height: 49px; width: 1000px;"> + <thead> + <tr> + <th scope="col">Specification</th> + <th scope="col">Status</th> + <th scope="col">Comment</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{SpecName('DOM3 Events','#interface-UIEvent','UIEvent()')}}</td> + <td>{{Spec2('DOM3 Events')}}</td> + <td>原始定義。</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器支援度">瀏覽器支援度</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatGeckoDesktop(11) }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatGeckoMobile(11) }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="延伸閱讀">延伸閱讀</h2> + +<ul> + <li>{{domxref("UIEvent")}}，此 constructer 所建立的 object 的 interface。</li> +</ul> diff --git a/files/zh-tw/web/api/url/createobjecturl/index.html b/files/zh-tw/web/api/url/createobjecturl/index.html new file mode 100644 index 0000000000..8760dffaec --- /dev/null +++ b/files/zh-tw/web/api/url/createobjecturl/index.html @@ -0,0 +1,137 @@ +--- +title: URL.createObjectURL() +slug: Web/API/URL/createObjectURL +translation_of: Web/API/URL/createObjectURL +--- +<div>{{ApiRef("URL API")}}{{SeeCompatTable}}</div> + +<h2 id="摘要">摘要</h2> + +<p>靜態方法 <strong><code>URL.createObjectURL()</code></strong> 用於建立一個帶有URL的 {{domxref("DOMString")}} 以代表參數中所傳入的物件. 該URL的生命週期與創造它的window中的 {{domxref("document")}}一致. 這個新的物件URL 代表了所指定的 {{domxref("File")}} 物件 或是 {{domxref("Blob")}} 物件.</p> + +<p>{{AvailableInWorkers}}</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><em>objectURL</em> = URL.createObjectURL(<em>blob</em>); +</pre> + +<h2 id="參數">參數</h2> + +<dl> + <dt><em>blob</em></dt> +</dl> + +<dl> + <dd>一個用以建立物件URL的 {{domxref("File")}} 物件 或是 {{domxref("Blob")}} 物件.</dd> +</dl> + +<ul> +</ul> + +<h2 id="範例">範例</h2> + +<p>參見 <a href="/en-US/docs/Using_files_from_web_applications#Example.3A_Using_object_URLs_to_display_images" title="https://developer.mozilla.org/en/Using_files_from_web_applications#Example:_Using_object_URLs_to_display_images">Using object URLs to display images</a>.(藉由物件URL來顯示圖像)</p> + +<h2 id="注意事項">注意事項</h2> + +<p>每次呼叫 <code>createObjectURL()</code> 都會產生一個新的URL, 不論是否曾以同一物件產生過. 當你不再需要它們的時候必須對每一個都呼叫 {{domxref("URL.revokeObjectURL()")}} 來釋放它們. 瀏覽器會在document被unload時自動釋放它們; 然而, 為了最佳化效能與記憶體用量, 當有安全的時機請務必手動釋放它們.</p> + +<h2 id="規範文件">規範文件</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規範文件</th> + <th scope="col">狀態</th> + <th scope="col">附註</th> + </tr> + <tr> + <td>{{SpecName('File API', '#dfn-createObjectURL', 'URL')}}</td> + <td>{{Spec2('File API')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>功能</th> + <th>Chrome</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>8 [1]<br> + {{CompatChrome(23)}}</td> + <td>{{CompatGeckoDesktop(2)}}</td> + <td>{{CompatIE(10)}}</td> + <td>{{CompatOpera(15)}}</td> + <td>{{CompatSafari(6)}} [1]<br> + {{CompatSafari(7)}}</td> + </tr> + <tr> + <td>In a {{ domxref("Worker", "Web Worker") }}</td> + <td>10 [1]<br> + {{CompatChrome(23)}}</td> + <td>{{CompatGeckoDesktop(21)}}</td> + <td>{{CompatIE(11)}}</td> + <td>{{CompatOpera(15)}}</td> + <td>{{CompatSafari(6)}} [1]<br> + {{CompatSafari(7)}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Chrome for Android</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>18 [1]</td> + <td>4.0 [1]</td> + <td>{{CompatGeckoMobile(14)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatOpera(15)}} [1]</td> + <td>6.0 [1]</td> + </tr> + <tr> + <td>In a {{ domxref("Worker", "Web Worker") }}</td> + <td>18 [1]</td> + <td>{{CompatVersionUnknown}} [1]</td> + <td>{{CompatGeckoMobile(14)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatOpera(15)}} [1]</td> + <td>6.0 [1]</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] 在該瀏覽器中必須使用 <code>webkitURL 而非 <a href="/en-US/docs/Web/API/URL">URL</a></code></p> + +<h2 id="另見">另見</h2> + +<ul> + <li>{{domxref("URL.revokeObjectURL()")}}</li> + <li><a href="/en-US/docs/Using_files_from_web_applications" title="Using files from web applications">Using files from web applications</a></li> +</ul> diff --git a/files/zh-tw/web/api/url/index.html b/files/zh-tw/web/api/url/index.html new file mode 100644 index 0000000000..0a7fdb670b --- /dev/null +++ b/files/zh-tw/web/api/url/index.html @@ -0,0 +1,212 @@ +--- +title: URL +slug: Web/API/URL +tags: + - API + - Experimental + - NeedsTranslation + - TopicStub + - URL API +translation_of: Web/API/URL +--- +<div>{{ApiRef("URL API")}} {{SeeCompatTable}}</div> + +<p><strong><code>URL</code></strong> 介面提供了建立 <code>URL</code> 物件的靜態方法。</p> + +<p>使用尚未實作此物件的瀏覽器時，可以改用 {{domxref("Window.URL")}} 屬性來呼叫（基於 Webkit 或 Blink 引擎的瀏覽器可使用 <code>Window.webkitURL</code>）。</p> + +<p>{{AvailableInWorkers}}</p> + +<h2 id="屬性">屬性</h2> + +<dl> + <dt>{{domxref("URL.href")}}</dt> + <dd>Is a {{domxref("DOMString")}} containing the whole URL.</dd> + <dt>{{domxref("URL.protocol")}}</dt> + <dd>Is a {{domxref("DOMString")}} containing the protocol scheme of the URL, including the final <code>':'</code>.</dd> + <dt>{{domxref("URL.host")}}</dt> + <dd>Is a {{domxref("DOMString")}} containing the host, that is the <em>hostname</em>, a <code>':'</code>, and the <em>port</em> of the URL.</dd> + <dt>{{domxref("URL.hostname")}}</dt> + <dd>Is a {{domxref("DOMString")}} containing the domain of the URL.</dd> + <dt>{{domxref("URL.port")}}</dt> + <dd>Is a {{domxref("DOMString")}} containing the port number of the URL.</dd> + <dt>{{domxref("URL.pathname")}}</dt> + <dd>Is a {{domxref("DOMString")}} containing an initial <code>'/'</code> followed by the path of the URL.</dd> + <dt>{{domxref("URL.search")}}</dt> + <dd>Is a {{domxref("DOMString")}} containing a <code>'?'</code> followed by the parameters of the URL.</dd> + <dt>{{domxref("URL.hash")}}</dt> + <dd>Is a {{domxref("DOMString")}} containing a <code>'#'</code> followed by the fragment identifier of the URL.</dd> + <dt>{{domxref("URL.username")}}</dt> + <dd>Is a {{domxref("DOMString")}} containing the username specified before the domain name.</dd> + <dt>{{domxref("URL.password")}}</dt> + <dd>Is a {{domxref("DOMString")}} containing the password specified before the domain name.</dd> + <dt>{{domxref("URL.origin")}} {{readonlyInline}}</dt> + <dd>Returns a {{domxref("DOMString")}} containing the origin of the URL, that is its scheme, its domain and its port.</dd> +</dl> + +<dl> + <dt>{{domxref("URL.searchParams")}}</dt> + <dd>Returns a {{domxref("URLSearchParams")}} object allowing to access the GET query arguments contained in the URL.</dd> +</dl> + +<h2 id="建構式">建構式</h2> + +<dl> + <dt>{{domxref("URL.URL", "URL()")}}</dt> + <dd>Creates and return a <code>URL</code> object composed from the given parameters.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>The <code>URL</code> interface implements methods defined in {{domxref("URLUtils")}}.</em></p> + +<dl> + <dt>{{domxref("URLUtils.toString()")}}</dt> + <dd>Returns a {{domxref("DOMString")}} containing the whole URL. It is a synonym for {{domxref("URLUtils.href")}}, though it can't be used to modify the value.</dd> +</dl> + +<h2 id="靜態方法">靜態方法</h2> + +<dl> + <dt>{{domxref("URL.createObjectURL()")}}</dt> + <dd>Returns a {{domxref("DOMString")}} containing a unique blob URL, that is a URL with <code>blob:</code> as its scheme, followed by an opaque string uniquely identifying the object in the browser.</dd> + <dt>{{domxref("URL.revokeObjectURL()")}}</dt> + <dd>Revokes an object URL previously created using {{domxref("URL.createObjectURL()")}}.</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('File API', '#creating-revoking', 'URL')}}</td> + <td>{{Spec2('File API')}}</td> + <td>Added the static methods <code>URL.createObjectURL()</code> and <code>URL.revokeObjectURL</code><code>()</code>.</td> + </tr> + <tr> + <td>{{SpecName('URL', '#api', 'Node')}}</td> + <td>{{Spec2('URL')}}</td> + <td>Initial definition (implements <code>URLUtils</code>).</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>8.0<sup>[2]</sup><br> + 32</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoDesktop("2.0")}}<sup>[1][3]</sup><br> + {{CompatGeckoDesktop("19.0")}}</td> + <td>10.0</td> + <td>15.0<sup>[2]</sup><br> + 19</td> + <td>6.0<sup>[2]</sup><br> + 7.0</td> + </tr> + <tr> + <td><code>username</code>, <code>password</code>, and <code>origin</code></td> + <td>32</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoDesktop("26.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>19</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>searchParams</code></td> + <td>{{CompatChrome(49)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoDesktop("29.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>36</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>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>4<sup>[2]</sup><br> + 4.4</td> + <td>8.0<sup>[2]</sup><br> + 32</td> + <td>{{CompatGeckoMobile("14.0")}}<sup>[1][3]</sup><br> + {{CompatGeckoMobile("19.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>15.0<sup>[2]</sup></td> + <td>6.0<sup>[2]</sup></td> + </tr> + <tr> + <td><code>username</code>, <code>password</code>, and <code>origin</code></td> + <td>4.4</td> + <td>32</td> + <td>{{CompatGeckoDesktop("26.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>searchParams</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatChrome(49)}}</td> + <td>{{CompatGeckoMobile("29.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] From Gecko 2 (Firefox 4) to Gecko 18 included, Gecko supported this interface with the non-standard <code>nsIDOMMozURLProperty</code> internal type. As the only to access such an object was through {{domxref("window.URL")}}, in practice, this didn't make any difference.</p> + +<p>[2] This feature is implemented under the non-standard name <code>webkitURL</code>.</p> + +<p>[3] For Firefox, to use from chrome code, JSM and Bootstrap scope, you have to import it like this:</p> + +<pre class="brush: js">Cu.importGlobalProperties(['URL']); +</pre> + +<p><code>URL</code> is available in Worker scopes.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>Property allowing to get such an object: {{domxref("Window.URL")}}.</li> + <li><a href="/en-US/docs/Components.utils.importGlobalProperties">Components.utils.importGlobalProperties</a></li> +</ul> diff --git a/files/zh-tw/web/api/validitystate/index.html b/files/zh-tw/web/api/validitystate/index.html new file mode 100644 index 0000000000..8cd2bdd738 --- /dev/null +++ b/files/zh-tw/web/api/validitystate/index.html @@ -0,0 +1,145 @@ +--- +title: ValidityState +slug: Web/API/ValidityState +translation_of: Web/API/ValidityState +--- +<div>{{APIRef("HTML DOM")}} {{gecko_minversion_header("2.0")}}</div> + +<p><strong><code>ValidityState</code></strong> 介面表示了一個元素目前在其檢核條件下驗證的<em>正確性狀態（validity states）</em>。同時，它們也可以協助解釋元素值檢核失敗的原因，如果元素值為不合法的。</p> + +<h2 id="屬性">屬性</h2> + +<p>For each of these Boolean properties, a value of <code>true</code> indicates that the specified reason validation may have failed is true, with the exception of the valid property, which is <code>true</code> if the element's value obeys all constraints.</p> + +<dl> + <dt>{{domxref("ValidityState.badInput")}} {{ReadOnlyInline}}</dt> + <dd>Is a {{jsxref("Boolean")}} indicating the user has provided input that the browser is unable to convert.</dd> + <dt>{{domxref("ValidityState.customError")}} {{ReadOnlyInline}}</dt> + <dd>Is a {{jsxref("Boolean")}} indicating the element's custom validity message has been set to a non-empty string by calling the element's <code>setCustomValidity()</code> method.</dd> + <dt>{{domxref("ValidityState.patternMismatch")}} {{ReadOnlyInline}}</dt> + <dd>Is a {{jsxref("Boolean")}} indicating the value does not match the specified {{htmlattrxref("pattern", "input")}}.</dd> + <dt>{{domxref("ValidityState.rangeOverflow")}} {{ReadOnlyInline}}</dt> + <dd>Is a {{jsxref("Boolean")}} indicating the value is greater than the maximum specified by the {{htmlattrxref("max", "input")}} attribute.</dd> + <dt>{{domxref("ValidityState.rangeUnderflow")}} {{ReadOnlyInline}}</dt> + <dd>Is a {{jsxref("Boolean")}} indicating the value is less than the minimum specified by the {{htmlattrxref("min", "input")}} attribute.</dd> + <dt>{{domxref("ValidityState.stepMismatch")}} {{ReadOnlyInline}}</dt> + <dd>Is a {{jsxref("Boolean")}} indicating the value does not fit the rules determined by the {{htmlattrxref("step", "input")}} attribute (that is, it's not evenly divisible by the step value).</dd> + <dt>{{domxref("ValidityState.tooLong")}} {{ReadOnlyInline}}</dt> + <dd>Is a {{jsxref("Boolean")}} indicating the value exceeds the specified <code>maxlength</code> for {{domxref("HTMLInputElement")}} or {{domxref("HTMLTextAreaElement")}} objects. <em><strong>Note:</strong> This will never be <code>true</code> in Gecko, because elements' values are prevented from being longer than <code>maxlength</code>.</em></dd> + <dt>{{domxref("ValidityState.tooShort")}} {{ReadOnlyInline}}</dt> + <dd>Is a {{jsxref("Boolean")}} indicating the value fails to meet the specified <code>minlength</code> for {{domxref("HTMLInputElement")}} or {{domxref("HTMLTextAreaElement")}} objects.</dd> + <dt>{{domxref("ValidityState.typeMismatch")}} {{ReadOnlyInline}}</dt> + <dd>Is a {{jsxref("Boolean")}} indicating the value is not in the required syntax (when {{htmlattrxref("type", "input")}} is <code>email</code> or <code>url</code>).</dd> + <dt>{{domxref("ValidityState.valid")}} {{ReadOnlyInline}}</dt> + <dd>Is a {{jsxref("Boolean")}} indicating the element meets all constraint validations, and is therefore considered to be valid.</dd> + <dt>{{domxref("ValidityState.valueMissing")}} {{ReadOnlyInline}}</dt> + <dd>Is a {{jsxref("Boolean")}} indicating the element has a {{htmlattrxref("required", "input")}} attribute, but no value.</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('HTML WHATWG', 'forms.html#the-constraint-validation-api', 'ValidityState') }}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>Live Standard</td> + </tr> + <tr> + <td>{{ SpecName('HTML5.1', '#the-constraint-validation-api', 'ValidityState') }}</td> + <td>{{Spec2('HTML5.1')}}</td> + <td>No change from the previous snapshot {{SpecName('HTML5 W3C')}}.</td> + </tr> + <tr> + <td>{{ SpecName('HTML5 W3C', 'forms.html#the-constraint-validation-api', 'ValidityState') }}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>First snapshot of {{SpecName('HTML WHATWG')}} containing this interface.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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>{{ CompatVersionUnknown() }}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{ CompatVersionUnknown }}</td> + <td>10</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>10.0.3</td> + </tr> + <tr> + <td><code>badInput</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(29)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>10.0.3</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatVersionUnknown() }}</td> + </tr> + <tr> + <td><code>badIndput</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile(29)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation">Constraint validation</a></li> + <li><a href="/en-US/docs/Web/Guide/HTML/Forms/Data_form_validation">Forms: Data form validation</a></li> +</ul> diff --git a/files/zh-tw/web/api/vibration_api/index.html b/files/zh-tw/web/api/vibration_api/index.html new file mode 100644 index 0000000000..115020dbda --- /dev/null +++ b/files/zh-tw/web/api/vibration_api/index.html @@ -0,0 +1,113 @@ +--- +title: Vibration API +slug: Web/API/Vibration_API +translation_of: Web/API/Vibration_API +--- +<p>{{DefaultAPISidebar("Vibration API")}}</p> + +<p>目前大多數的行動裝置均具備振動硬體以搖晃裝置，讓軟體程式碼能對使用者產生實際反饋。<strong>Vibration API</strong> 即可讓 Web Apps 存取振動硬體。當然，若裝置並未支援振動硬體，就不會產生任何效果。</p> + +<h2 id="振動說明">振動說明</h2> + +<p>振動即如「on-off」脈衝的形式，且持續時間亦有不同的變化。可透過單一整數讓振動持續數個毫秒 (ms)；或可由多個整數組成陣列，達到振動與暫停交錯的振動形式。只要單一 <a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.vibrate" title="/en-US/docs/Web/API/window.navigator.vibrate"><code>window.navigator.vibrate()</code></a> 函式即可控制振動。</p> + +<h3 id="單次振動">單次振動</h3> + +<p>你可指定單一數值，或用單一數值構成 1 組陣列，讓振動硬體動作 1 次：</p> + +<pre class="brush:js">window.navigator.vibrate(200); +window.navigator.vibrate([200]); +</pre> + +<p>上列 2 個範例均可使裝置振動達 200 ms。</p> + +<h3 id="振動形式">振動形式</h3> + +<p>用數值構成陣列，敘述裝置在一段期間內振動與停止振動的情形。陣列中的所有值均轉換為整數，接著直譯 (Interprete) 成裝置振動與停止振動的毫秒數。範例如下：</p> + +<pre class="brush: js">window.navigator.vibrate([200, 100, 200]); +</pre> + +<p>根據此陣列，裝置將振動 200 ms、暫停 100 ms，再振動 200 ms。</p> + +<p>你可照自己喜好而指定多組振動/暫停的變化，且輸入項的數量為奇數或偶數均可。由於振動將在每個振動期間結束時停止，所以不一定要提供暫停數值作為最後 1 組輸入項。</p> + +<h3 id="取消目前振動">取消目前振動</h3> + +<p><code>在</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.vibrate" title="/en-US/docs/Web/API/window.navigator.vibrate"><code>window.navigator.vibrate()</code></a><code> 的值為「0」、空白陣列，或陣列全為「0」時呼叫此函式，即可取消目前執行中的振動作業。</code></p> + +<h2 id="規格">規格</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('Vibration API')}}</td> + <td>{{Spec2('Vibration API')}}</td> + <td>Initial specification.</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>{{CompatVersionUnknown}} {{property_prefix("webkit")}}</td> + <td>11.0 {{property_prefix("moz")}}<br> + 16 (no prefix)</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</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>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}} {{property_prefix("webkit")}}</td> + <td>11.0 {{property_prefix("moz")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="另可參閱">另可參閱</h2> + +<ul> + <li>{{domxref("window.navigator.vibrate()")}}</li> +</ul> diff --git a/files/zh-tw/web/api/web_audio_api/index.html b/files/zh-tw/web/api/web_audio_api/index.html new file mode 100644 index 0000000000..f2eef8f535 --- /dev/null +++ b/files/zh-tw/web/api/web_audio_api/index.html @@ -0,0 +1,119 @@ +--- +title: Web Audio API +slug: Web/API/Web_Audio_API +translation_of: Web/API/Web_Audio_API +--- +<p>{{SeeCompatTable}}</p> +<p><img alt="Show the ability of AudioNodes to connect via their inputs and outputs and the channels inside these inputs/outputs." src="https://mdn.mozillademos.org/files/5183/WebAudioGenerics.png" style="width: 338px; height: 349px; float: left;"><strong>Web Audio API</strong> 可於 Web App 或網頁上操作並播放音訊檔案。</p> +<p>Web Audio API 是根據模組化路由 (Modular routing) 的概念所設計。所謂的模組化路由，即是以<strong>「音訊節點</strong><strong> (Audio nodes)</strong><strong>」</strong>執行基本的音訊作業<strong>，</strong>節點又互相連接而構成「音訊路由圖 (Audio routing graphs)」。在同一環境 (Audio context) 內，又可支援數個音源與多樣的聲道配置。此模組化設計可提供更高的靈活度，並能建立複雜的音訊函式與動態效果。</p> +<p>音訊節點均透過其輸出與輸入而相互連結。各個輸入/輸出均具備數個<strong>聲道</strong><strong> (Channel)</strong><strong>，以構成特定的音訊配置。但目前已可支援單聲道、立體聲、四聲道、</strong>5.1 聲道等配置，並支援其他的離散配置。</p> +<p>音訊有多種來源。可能由特定的音訊節點 (如震盪器、自訂函式，甚或簡易的資料陣列) 直接在 JavaScript 中產生。音源除了可連至 HTML 媒體元素 (如 <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video" title="The HTML <video> element is used to embed video content in an HTML or XHTML document."><code><video></code></a> 或 <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio" title="The HTML <audio> element is used to represents sound content in documents. Added as part of HTML5, it may contain several audio sources, represented using the src attribute or the <source> element; the browser will choose the most suitable one. Fallback c"><code><audio></code></a>)，亦可能來自於 <a href="https://developer.mozilla.org/en-US/docs/WebRTC" title="/en-US/docs/WebRTC">WebRTC</a> 的 <a href="https://developer.mozilla.org/en-US/docs/Web/API/MediaStream" title="The MediaStream interface represents a stream of media content. A stream consists of several tracks, like video or audio tracks."><code>MediaStream</code></a> (本端裝置的相機或遠方電腦)。</p> +<p>特定音訊事件發生的時間點，均達到極高的精確度與極低的潛時，因此亦可用以詳細定義鼓類機器或音序器 (Sequencer) 所需的事件。</p> +<p>Web Audio API 亦可控制音訊的空間定位 (Spatialized) 作業：透過 source-listener 模型架構的系統，進而控制所要使用的左右相位 (Panning<em>，</em>聲音放置於左右喇叭之間形成的立體音場中，以產生出空間感) 模<em>型</em>，進而自動處理因距離遠近所產生的衰減，或是由於音源/聽者移動所發生的都卜勒移頻 (Doppler shift)。</p> +<h2 id="參考">參考</h2> +<div class="index"> + <ul> + <li>{{domxref("AnalyserNode")}}</li> + <li>{{domxref("AudioBuffer")}}</li> + <li>{{domxref("AudioBufferSourceNode")}}</li> + <li>{{domxref("AudioContext")}}</li> + <li>{{domxref("AudioDestinationNode")}}</li> + <li>{{domxref("AudioListener")}}</li> + <li>{{domxref("AudioNode")}}</li> + <li>{{domxref("AudioParam")}}</li> + <li>{{event("audioprocess")}} (event)</li> + <li>{{domxref("AudioProcessingEvent")}}</li> + <li>{{domxref("BiquadFilterNode")}}</li> + <li>{{domxref("ChannelMergerNode")}}</li> + <li>{{domxref("ChannelSplitterNode")}}</li> + <li>{{event("complete")}} (event)</li> + <li>{{domxref("ConvolverNode")}}</li> + <li>{{domxref("DelayNode")}}</li> + <li>{{domxref("DynamicsCompressorNode")}}</li> + <li>{{event("ended_(Web_Audio)", "ended")}} (event)</li> + <li>{{domxref("GainNode")}}</li> + <li>{{domxref("MediaElementAudioSourceNode")}}</li> + <li>{{domxref("MediaStreamAudioDestinationNode")}}</li> + <li>{{domxref("MediaStreamAudioSourceNode")}}</li> + <li>{{domxref("OfflineAudioCompletionEvent")}}</li> + <li>{{domxref("OfflineAudioContext")}}</li> + <li>{{domxref("OscillatorNode")}}</li> + <li>{{domxref("PannerNode")}}</li> + <li>{{domxref("ScriptProcessorNode")}}</li> + <li>{{domxref("WaveShaperNode")}}</li> + <li> </li> + </ul> +</div> +<h2 id="線上教學">線上教學</h2> +<ul> + <li>使用 Web Audio API</li> + <li><a href="http://www.html5rocks.com/tutorials/webaudio/intro/" title="http://www.html5rocks.com/tutorials/webaudio/intro/">Getting Started with the Web Audio API</a> (僅說明 WebKit-only 的非標準建置)</li> + <li><a href="http://www.html5rocks.com/tutorials/webaudio/positional_audio/" title="http://www.html5rocks.com/tutorials/webaudio/positional_audio/">混合定位音訊 (Positional Audio) 與 WebGL</a></li> + <li><a href="http://www.html5rocks.com/tutorials/webaudio/games/" title="http://www.html5rocks.com/tutorials/webaudio/games/">以 Web Audio API 開發遊戲音訊</a></li> + <li><a href="/en-US/docs/Web_Audio_API/Porting_webkitAudioContext_code_to_standards_based_AudioContext" title="/en-US/docs/Web_Audio_API/Porting_webkitAudioContext_code_to_standards_based_AudioContext">將 webkitAudioContext 程式碼移植為標準的 AudioContext</a></li> +</ul> +<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('Web Audio API')}}</td> + <td>{{Spec2('Web Audio API')}}</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>14 {{property_prefix("webkit")}}</td> + <td>23</td> + <td>{{CompatNo}}</td> + <td>15 {{property_prefix("webkit")}}</td> + <td>6 {{property_prefix("webkit")}}</td> + </tr> + </tbody> + </table> +</div> +<div id="compat-mobile"> + <table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatNo}}</td> + <td>28 {{property_prefix("webkit")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>6 {{property_prefix("webkit")}}</td> + </tr> + </tbody> + </table> +</div> +<p> </p> diff --git a/files/zh-tw/web/api/web_video_text_tracks_format/index.html b/files/zh-tw/web/api/web_video_text_tracks_format/index.html new file mode 100644 index 0000000000..e565d2d129 --- /dev/null +++ b/files/zh-tw/web/api/web_video_text_tracks_format/index.html @@ -0,0 +1,691 @@ +--- +title: WebVTT +slug: Web/API/Web_Video_Text_Tracks_Format +translation_of: Web/API/WebVTT_API +--- +<p>WebVTT 是一種 UTF-8 編碼的文字檔案格式，可藉由 {{ HTMLElement("track") }} 元素顯示加註時間資訊之文字軌，其主要設計目的是為 {{ HTMLElement("video") }} 顯示字幕。</p> + +<p>WebVTT 當中可以採用空白或分隔字元（tab）。</p> + +<p>WebVTT 的 MIME Type 為 <code>text/vtt</code>。</p> + +<p> </p> + +<h2 id="WebVTT_文本">WebVTT 文本</h2> + +<p>WebVTT 檔的結構中，有兩項必備資訊、四項選用資訊。</p> + +<ul> + <li>選用：byte order mark (BOM)</li> + <li>字串 <code>WEBVTT</code></li> + <li>選用：於 <code>WEBVTT</code> 右側可加上文字標題 + <ul> + <li>在 <code>WEBVTT</code> 之後至少要有一個空白字元</li> + <li>可以藉此為檔案加上描述</li> + <li>除了換行字元及<code>「--></code>」字串外，可以是任何文字</li> + </ul> + </li> + <li>一個空白行，由兩個連續的換行字元構成。</li> + <li>選用：一個以上的時間節點（cue）或註解</li> + <li>選用：一個以上的空白行</li> +</ul> + +<h5 id="範例_1_-_最簡單的_WEBVTT_檔">範例 1 - 最簡單的 WEBVTT 檔</h5> + +<pre> WEBVTT + +</pre> + +<h5 id="範例_2_-_很簡單的_WebVTT_檔">範例 2 - 很簡單的 WebVTT 檔</h5> + +<pre> WEBVTT - 這個檔案沒有時間節點 + +</pre> + +<h5 id="範例_3_-_常見的_WebVTT_例子">範例 3 - 常見的 WebVTT 例子</h5> + +<pre> WEBVTT - 這個檔案有時間節點 + + 14 + 00:01:14.815 --> 00:01:18.114 + - What? + - Where are we now? + + 15 + 00:01:18.171 --> 00:01:20.991 + - This is big bat country. + + 16 + 00:01:21.058 --> 00:01:23.868 + - [ Bats Screeching ] + - They won't get in your hair. They're after the bugs. +</pre> + +<p> </p> + +<h2 id="WebVTT_註解">WebVTT 註解</h2> + +<p>Comments are an optional component that can be used to add information to a WebVTT file. Comments are intended for those reading the file and are not seen by users. Comments may contain newlines but it cannot contain a blank line, which is equivalent to two consecutive newlines. A blank line signifies the end of a comment.</p> + +<p>註解中不能包含「<code>-->」字串、「</code>&」符號或「<」符號。如欲使用後兩者，可採跳脫字串「&amp;」或「&lt;」。此外雖規格上允許使用「>」字元，仍然建議跳脫為「&gt;」以避免混淆。</p> + +<p>註解由三個部分組成：</p> + +<ul> + <li>字串 <code>NOTE</code></li> + <li>一個空白字元或換行字元</li> + <li>選用：一個以上的字元，除了前面提到的禁用字元外皆可使用</li> +</ul> + +<h5 id="範例_4_-_常見_WebVTT_範例">範例 4 - 常見 WebVTT 範例</h5> + +<pre> NOTE 這行是註解 +</pre> + +<h5 id="範例_5_-_多行註解">範例 5 - 多行註解</h5> + +<pre> NOTE + 這也是註解， + 只是拆成多行。 + + NOTE 當然也可以像這樣 + 來分行寫註解。 +</pre> + +<h5 id="範例_6_-_常見註解使用方式">範例 6 - 常見註解使用方式</h5> + +<pre> WEBVTT - 翻譯我喜歡的影片字幕 + + NOTE + 本字幕由 Kyle 翻譯， + 希望可以讓我的朋友跟家人一同觀賞。 + + 1 + 00:02:15.000 --> 00:02:20.000 + - Ta en kopp varmt te. + - Det är inte varmt. + + 2 + 00:02:20.000 --> 00:02:25.000 + - Har en kopp te. + - Det smakar som te. + + NOTE This last line may not translate well. + + 3 + 00:02:25.000 --> 00:02:30.000 + -Ta en kopp. +</pre> + +<p> </p> + +<h2 id="WebVTT_時間節點">WebVTT 時間節點</h2> + +<p>時間節點（cue）是具備單一開始時間、結束時間、文字內容的字幕區段。 Example 6 consists of the header, a blank line, and then five cues separated by blank lines. 時間節點由五個部分組成：</p> + +<ul> + <li>選用：時間節點 ID，後接著一個換行字元</li> + <li>時間資訊</li> + <li>選用：時間節點設定，每個設定值以空白字元分隔，第一個設定值前也要加個空白字元</li> + <li>一個以上的換行字元</li> + <li>文字內容</li> +</ul> + +<h5 id="範例7_-_Example_of_a_cue">範例7 - Example of a cue</h5> + +<pre>1 - Title Crawl +00:00:5.000 --> 00:00:10.000 line:0 position:20% size:60% align:start +Some time ago in a place rather distant....</pre> + +<p> </p> + +<h3 id="節點_ID">節點 ID</h3> + +<p>此 ID 代表時間節點的名稱，可以用以在腳本語言中參照某段特定時間節點。ID 中禁用換行字元，也不可以包括「<code>-->」字串。</code>ID 最後必須以一個換行字元作為結束。</p> + +<p>雖然通常都用數字（1, 2, 3...）作為 ID，但規格上並不要求每個 ID 都是為一值。</p> + +<h5 id="範例_8_-_範例_7_中的時間節點_ID">範例 8 - 範例 7 中的時間節點 ID</h5> + +<pre>1 - Title Crawl</pre> + +<h5 id="範例_9_-_ID_常見用法">範例 9 - ID 常見用法</h5> + +<pre>WEBVTT + +1 +00:00:22.230 --> 00:00:24.606 +This is the first subtitle. + +2 +00:00:30.739 --> 00:00:34.074 +This is the second. + +3 +00:00:34.159 --> 00:00:35.743 +Third +</pre> + +<p> </p> + +<h3 id="時間資訊">時間資訊</h3> + +<p>時間資訊標注了此段節點的出現時機，其中包括開始時間與結束時間。結束時間必須比開始時間晚，而開始時間必須比先前所有的開始時間晚，或至少是同一時間。</p> + +<p>不同時間節點可以設定為同時顯示，但若 WebVTT 檔案是用在 chapters（{{ HTMLElement("track") }} 的 {{ htmlattrxref("kind") }} 設定為 <code>chapters</code>），則不允許兩段節點同時出現。</p> + +<p>每項時間資訊都由五個部分組成：</p> + +<ul> + <li>開始時間</li> + <li>一個以上的空白字元</li> + <li>「<code>-->」字串</code></li> + <li>一個以上的空白字元</li> + <li>結束時間 + <ul> + <li>必須比開始時間晚</li> + </ul> + </li> +</ul> + +<p>時間的表示方式，可以是以下兩種：</p> + +<ul> + <li><code>mm:ss.ttt</code></li> + <li><code>hh:mm:ss.ttt</code></li> +</ul> + +<p>其中的各元素說明如下：</p> + +<ul> + <li><code>hh</code> - 小時 + + <ul> + <li>至少要有兩個數字，不小於 01</li> + <li>可以超過兩個數字（例如 9999:00:00.000）</li> + </ul> + </li> + <li><code>mm</code> - 分 + <ul> + <li>從 00 到 59</li> + </ul> + </li> + <li><code>ss</code> - 秒 + <ul> + <li>從 00 到 59</li> + </ul> + </li> + <li><code>ttt</code> - 毫秒 + <ul> + <li>從 000 到 999</li> + </ul> + </li> +</ul> + +<h5 id="Example_10_-_Basic_cue_timing_examples">Example 10 - Basic cue timing examples</h5> + +<pre>00:22.230 --> 00:24.606 +00:30.739 --> 00:00:34.074 +00:00:34.159 --> 00:35.743 +00:00:35.827 --> 00:00:40.122</pre> + +<h5 id="Example_11_-_Overlapping_cue_timing_examples">Example 11 - Overlapping cue timing examples</h5> + +<pre>00:00:00.000 --> 00:00:10.000 +00:00:05.000 --> 00:01:00.000 +00:00:30.000 --> 00:00:50.000</pre> + +<h5 id="Example_12_-_Non-overlapping_cue_timing_examples">Example 12 - Non-overlapping cue timing examples</h5> + +<pre>00:00:00.000 --> 00:00:10.000 +00:00:10.000 --> 00:01:00.581 +00:01:00.581 --> 00:02:00.100 +00:02:01.000 --> 00:02:01.000</pre> + +<p> </p> + +<h3 id="Cue_Settings">Cue Settings</h3> + +<p>Cue settings are optional components used to position where the cue payload text will be displayed over the video. This includes whether the text is displayed horizontally or vertically. There can be zero or more of them, and they can be used in any order so long as each setting is used no more than once.</p> + +<p>The cue settings are added to the right of the cue timings. There must be one or more spaces between the cue timing and the first setting and between each setting. A setting's name and value are separated by a colon. The settings are case sensitive so use lower case as shown. There are five cue settings:</p> + +<ul> + <li><strong>vertical</strong> + + <ul> + <li>水平方向</li> + </ul> + + <table style="margin-left: 30px;"> + <thead> + <tr> + <th colspan="2">Table 1 - vertical values</th> + </tr> + </thead> + <tbody> + <tr> + <th><code>vertical:rl</code></th> + <td>文字方向由右至左</td> + </tr> + <tr> + <th><code>vertical:lr</code></th> + <td>文字方向由左至右</td> + </tr> + </tbody> + </table> + </li> + <li><strong>line</strong> + <ul> + <li>Specifies where text appears vertically. If vertical is set, line specifies where text appears horizontally.</li> + <li>Value can be a line number + <ul> + <li>The line height is the height of the first line of the cue as it appears on the video</li> + <li>Positive numbers indicate top down</li> + <li>Negative numbers indicate bottom up</li> + </ul> + </li> + <li>Or value can be a percentage + <ul> + <li>Must be an integer (i.e. no decimals) between 0 and 100 inclusive</li> + <li>Must be followed by a percent sign (%)</li> + </ul> + </li> + </ul> + + <table style="margin-left: 30px;"> + <thead> + <tr> + <th colspan="4">Table 2 - line examples</th> + </tr> + </thead> + <tbody> + <tr> + <th> </th> + <th><code>vertical</code> 省略時</th> + <th><code>vertical:rl</code></th> + <th><code>vertical:lr</code></th> + </tr> + <tr> + <th><code>line:0</code></th> + <td>top</td> + <td>right</td> + <td>left</td> + </tr> + <tr> + <th><code>line:-1</code></th> + <td>bottom</td> + <td>left</td> + <td>right</td> + </tr> + <tr> + <th><code>line:0%</code></th> + <td>top</td> + <td>right</td> + <td>left</td> + </tr> + <tr> + <th><code>line:100%</code></th> + <td>bottom</td> + <td>left</td> + <td>right</td> + </tr> + </tbody> + </table> + </li> + <li><strong>position</strong> + <ul> + <li>Specifies where the text will appear horizontally. If vertical is set, position specifies where the text will appear vertically.</li> + <li>Value is a percentage</li> + <li>Must be an integer (no decimals) between 0 and 100 inclusive</li> + <li>Must be followed by a percent sign (%)</li> + </ul> + + <table style="margin-left: 30px;"> + <thead> + <tr> + <th colspan="4">Table 3 - position examples</th> + </tr> + </thead> + <tbody> + <tr> + <th> </th> + <th><code>vertical</code> 省略時</th> + <th><code>vertical:rl</code></th> + <th><code>vertical:lr</code></th> + </tr> + <tr> + <th><code>position:0%</code></th> + <td>left</td> + <td>top</td> + <td>top</td> + </tr> + <tr> + <th><code>position:100%</code></th> + <td>right</td> + <td>bottom</td> + <td>bottom</td> + </tr> + </tbody> + </table> + </li> + <li><strong>size</strong> + <ul> + <li>Specifies the width of the text area. If vertical is set, size specifies the height of the text area.</li> + <li>Value is a percentage</li> + <li>Must be an integer (i.e. no decimals) between 0 and 100 inclusive</li> + <li>Must be followed by a percent sign (%)</li> + </ul> + + <table style="margin-left: 30px;"> + <thead> + <tr> + <th colspan="4">Table 4 - size examples</th> + </tr> + </thead> + <tbody> + <tr> + <th> </th> + <th><code>vertical</code> 省略時</th> + <th><code>vertical:rl</code></th> + <th><code>vertical:lr</code></th> + </tr> + <tr> + <th><code>size:100%</code></th> + <td>full width</td> + <td>full height</td> + <td>full height</td> + </tr> + <tr> + <th><code>size:50%</code></th> + <td>half width</td> + <td>half height</td> + <td>half height</td> + </tr> + </tbody> + </table> + </li> + <li><strong>align</strong> + <ul> + <li>Specifies the alignment of the text. Text is aligned within the space given by the size cue setting if it is set.</li> + </ul> + + <table style="margin-left: 30px;"> + <thead> + <tr> + <th colspan="4">Table 5 - align values</th> + </tr> + </thead> + <tbody> + <tr> + <th> </th> + <th><code>vertical</code> 省略時</th> + <th><code>vertical:rl</code></th> + <th><code>vertical:lr</code></th> + </tr> + <tr> + <th><code>align:start</code></th> + <td>left</td> + <td>top</td> + <td>top</td> + </tr> + <tr> + <th><code>align:middle</code></th> + <td>centred horizontally</td> + <td>centred vertically</td> + <td>centred vertically</td> + </tr> + <tr> + <th><code>align:end</code></th> + <td>right</td> + <td>bottom</td> + <td>bottom</td> + </tr> + </tbody> + </table> + </li> +</ul> + +<h5 id="Example_13_-_Cue_setting_examples">Example 13 - Cue setting examples</h5> + +<p>The first line demonstrates no settings. The second line might be used to overlay text on a sign or label. The third line might be used for a title. The last line might be used for an Asian language.</p> + +<pre>00:00:5.000 --> 00:00:10.000 +00:00:5.000 --> 00:00:10.000 line:63% position:72% align:start +00:00:5.000 --> 00:00:10.000 line:0 position:20% size:60% align:start +00:00:5.000 --> 00:00:10.000 vertical:rt line:-1 align:end +</pre> + +<p> </p> + +<h3 id="文字內容">文字內容</h3> + +<p>The payload is where the main information or content is located. In normal usage the payload contains the subtitles to be displayed. The payload text may contain newlines but it cannot contain a blank line, which is equivalent to two consecutive newlines. A blank line signifies the end of a cue.</p> + +<p>文字內容中不能包含「<code>-->」字串、「</code>&」符號或「<」符號。如欲使用後兩者，可採跳脫字串「&amp;」或「&lt;」。此外雖規格上允許使用「>」字元，仍然建議跳脫為「&gt;」以避免混淆。若您使用 WebVTT 檔作為後設資料，則可不管這些限制。</p> + +<p>除了上述的三個跳脫字串外，還有其他四種跳脫字串，分列如下</p> + +<table> + <thead> + <tr> + <th colspan="3">Table 6 - 跳脫字串</th> + </tr> + </thead> + <tbody> + <tr> + <th>名稱</th> + <th>字元</th> + <th>跳脫字串</th> + </tr> + <tr> + <td>「與」</td> + <td>&</td> + <td><code>&amp;</code></td> + </tr> + <tr> + <td>小於</td> + <td><</td> + <td><code>&lt;</code></td> + </tr> + <tr> + <td>大於</td> + <td>></td> + <td><code>&gt;</code></td> + </tr> + <tr> + <td>左到右標記</td> + <td> </td> + <td><code>&lrm;</code></td> + </tr> + <tr> + <td>右到左標記</td> + <td> </td> + <td><code>&rlm;</code></td> + </tr> + <tr> + <td>不斷行空白</td> + <td><code> </code></td> + <td><code>&nbsp;</code></td> + </tr> + </tbody> +</table> + +<p> </p> + +<h3 id="文字內容中的標籤">文字內容中的標籤</h3> + +<p>有很多標籤（例如 <code><bold></code>）可以用在文字內容中，但若 {{ HTMLElement("track") }} 的 {{ htmlattrxref("kind") }} 設定為 <code>chapters</code> 時，其中所用的 WebVTT 檔案裡就不能使用標籤。</p> + +<ul> + <li><strong>時間標籤</strong> + + <ul> + <li>時間標籤中的時間，必須比該節點的開始時間晚、比同節點先前之其他時間標籤晚，並且早於該節點的結束時間。<em>當前文字（active text）</em> 代表此時間標籤到下個時間標籤（或文字內容的結尾）之間的文字，其他同節點中，比<em>當前文字</em> 早的文字都稱為<em>先前文字（previous text）</em> ，而晚於<em>當前文字</em> 的便稱為<em>未來文字（future text）</em> 。如此便可做出卡拉OK字幕效果</li> + </ul> + + <div style="margin-left: 30px;"> + <h5 id="Example_12_-_Karaoke_style_text">Example 12 - Karaoke style text</h5> + + <pre>1 +00:16.500 --> 00:18.500 +When the moon <00:17.500>hits your eye + +1 +00:00:18.500 --> 00:00:20.500 +Like a <00:19.000>big-a <00:19.500>pizza <00:20.000>pie + +1 +00:00:20.500 --> 00:00:21.500 +That's <00:00:21.000>amore + </pre> + </div> + </li> +</ul> + +<p> </p> + +<p>以下則需要開頭標籤與結束標籤（例如 <code><b>text</b></code>）。</p> + +<ul> + <li><strong>Class 標籤</strong>（<code><c></c></code>） + + <ul> + <li>以 CSS 類別為該段文字設定樣式</li> + </ul> + + <div style="margin-left: 30px;"> + <h5 id="Example_14_-_Class_tag">Example 14 - Class tag</h5> + + <pre><c.classname>text</c></pre> + </div> + </li> + <li><strong>Italics tag</strong> (<code><i></i></code>) + <ul> + <li>Italicize the contained text.</li> + </ul> + + <div style="margin-left: 30px;"> + <h5 id="Example_15_-_Italics_tag">Example 15 - Italics tag</h5> + + <pre><i>text</i></pre> + </div> + </li> + <li><strong>Bold tag</strong> (<code><b></b></code>) + <ul> + <li>Bold the contained text.</li> + </ul> + + <div style="margin-left: 30px;"> + <h5 id="Example_16_-_Bold_tag">Example 16 - Bold tag</h5> + + <pre><b>text</b></pre> + </div> + </li> + <li><strong>Underline tag</strong> (<code><u></u></code>) + <ul> + <li>Underline the contained text.</li> + </ul> + + <div style="margin-left: 30px;"> + <h5 id="Example_17_-_Underline_tag">Example 17 - Underline tag</h5> + + <pre><u>text</u></pre> + </div> + </li> + <li><strong>Ruby tag</strong> (<code><ruby></ruby></code>) + <ul> + <li>Used with ruby text tags to display <a href="http://en.wikipedia.org/wiki/Ruby_character">ruby characters</a> (i.e. small annotative characters above other characters).</li> + </ul> + + <div style="margin-left: 30px;"> + <h5 id="Example_18_-_Ruby_tag">Example 18 - Ruby tag</h5> + + <pre><ruby>WWW<rt>World Wide Web</rt>oui<rt>yes</rt></ruby></pre> + </div> + </li> + <li><strong>Ruby text tag</strong> (<code><rt></rt></code>) + <ul> + <li>Used with ruby tags to display <a href="http://en.wikipedia.org/wiki/Ruby_character">ruby characters</a> (i.e. small annotative characters above other characters).</li> + </ul> + + <div style="margin-left: 30px;"> + <h5 id="Example_19_-_Ruby_text_tag">Example 19 - Ruby text tag</h5> + + <pre><ruby>WWW<rt>World Wide Web</rt>oui<rt>yes</rt></ruby></pre> + </div> + </li> + <li><strong>Voice tag</strong> (<code><v></v></code>) + <ul> + <li>Similar to class tag, also used to style the contained text using CSS.</li> + </ul> + + <div style="margin-left: 30px;"> + <h5 id="Example_20_-_Voice_tag">Example 20 - Voice tag</h5> + + <pre><v Bob>text</v></pre> + </div> + </li> +</ul> + +<p> </p> + +<h2 id="瀏覽器支援">瀏覽器支援</h2> + +<p>{{ CompatibilityTable() }}</p> + +<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>基本支援</td> + <td>18 以上</td> + <td>24 (<a href="https://wiki.mozilla.org/WebVTT" title="https://wiki.mozilla.org/WebVTT">預設為關閉</a>)</td> + <td>10 以上</td> + <td>15.0 以上</td> + <td> 7 以上</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IChrome for Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>基本支援</td> + <td>4.4 以上</td> + <td> 目前尚不支援</td> + <td> 35.0 以上</td> + <td> 21.0 以上</td> + <td>7 以上</td> + </tr> + </tbody> +</table> + +<p> </p> + +<p> </p> +</div> + +<h2 id="規格">規格</h2> + +<ul> + <li><a class="external" href="http://dev.w3.org/html5/webvtt/" title="http://dev.w3.org/html5/webvtt/">http://dev.w3.org/html5/webvtt/</a></li> +</ul> diff --git a/files/zh-tw/web/api/web_workers_api/index.html b/files/zh-tw/web/api/web_workers_api/index.html new file mode 100644 index 0000000000..ba18e065dd --- /dev/null +++ b/files/zh-tw/web/api/web_workers_api/index.html @@ -0,0 +1,215 @@ +--- +title: Web Workers API +slug: Web/API/Web_Workers_API +translation_of: Web/API/Web_Workers_API +--- +<p>{{DefaultAPISidebar("Web Workers API")}}</p> + +<p class="summary"><strong>Web Workers</strong> are a mechanism by which a script operation can be made to run in a background thread separate from the main execution thread of a web application. The advantage of this is that laborious processing can be performed in a separate thread, allowing the main (usually the UI) thread to run without being blocked/slowed down.</p> + +<h2 id="Web_Workers_concepts_and_usage">Web Workers concepts and usage</h2> + +<p>A worker is an object created using <code>a</code> constructor (e.g. {{domxref("Worker.Worker", "Worker()")}}) that runs a named JavaScript file — this file contains the code that will run in the worker thread; workers run in another global context that is different from the current {{domxref("window")}}. This context is represented by a {{domxref("DedicatedWorkerGlobalScope")}} object in the case of dedicated workers (standard workers that are utilized by a single script; shared workers use {{domxref("SharedWorkerGlobalScope")}}).</p> + +<p>You can run whatever code you like inside the worker thread, with some exceptions. For example, you can't directly manipulate the DOM from inside a worker, or use some default methods and properties of the {{domxref("window")}} object. But you can use a large number of items available under <code>window</code>, including <a href="/en-US/docs/WebSockets">WebSockets</a>, and data storage mechanisms like <a href="/en-US/docs/Web/API/IndexedDB_API">IndexedDB</a> and the Firefox OS-only <a href="/en-US/docs/Web/API/Data_Store_API">Data Store API</a>. See <a href="/en-US/docs/Web/API/Worker/Functions_and_classes_available_to_workers">Functions and classes available to workers</a> for more details.</p> + +<p>Data is sent between workers and the main thread via a system of messages — both sides send their messages using the <code>postMessage()</code> method, and respond to messages via the <code>onmessage</code> event handler (the message is contained within the {{event("Message")}} event's data attribute.) The data is copied rather than shared.</p> + +<p>Workers may in turn spawn new workers, as long as those workers are hosted within the same origin as the parent page. In addition, workers may use <a class="internal" href="/en-US/docs/Web/API/XMLHttpRequest"><code>XMLHttpRequest</code></a> for network I/O, with the exception that the <code>responseXML</code> and <code>channel</code> attributes on <code>XMLHttpRequest</code> always return <code>null</code>.</p> + +<p>In addition to dedicated workers, there are other types of worker:</p> + +<ul> + <li>Shared workers are workers that can be utilized by multiple scripts running in different windows, IFrames, etc., as long as they are in the same domain as the worker. They are a little more complex than dedicated workers — scripts must communicate via an active port. See {{domxref("SharedWorker")}} for more details.</li> + <li><a href="/en-US/docs/Web/API/ServiceWorker_API">ServiceWorkers</a> essentially act as proxy servers that sit between web applications, and the browser and network (when available). They are intended to (amongst other things) enable the creation of effective offline experiences, intercepting network requests and taking appropriate action based on whether the network is available and updated assets reside on the server. They will also allow access to push notifications and background sync APIs.</li> + <li>Chrome Workers are a Firefox-only type of worker that you can use if you are developing add-ons and want to use workers in extensions and have access to <a href="https://developer.mozilla.org/en/js-ctypes">js-ctypes</a> in your worker. See {{domxref("ChromeWorker")}} for more details. </li> + <li><a href="/en-US/docs/Web/API/Web_Audio_API#Audio_Workers">Audio Workers</a> provide the ability for direct scripted audio processing to be done inside a web worker context.</li> +</ul> + +<div class="note"> +<p><strong>Note</strong>: As per the <a href="https://html.spec.whatwg.org/multipage/workers.html#runtime-script-errors-2">Web workers Spec</a>, worker error events should not bubble (see {{bug(1188141)}}. This has been implemented in Firefox 42.</p> +</div> + +<h2 id="Web_Worker_interfaces">Web Worker interfaces</h2> + +<dl> + <dt>{{domxref("AbstractWorker")}}</dt> + <dd>Abstracts properties and methods common to all kind of workers (i.e. {{domxref("Worker")}} or {{domxref("SharedWorker")}}).</dd> + <dt>{{domxref("Worker")}}</dt> + <dd>Represents a running worker thread, allowing you to pass messages to the running worker code.</dd> + <dt>{{domxref("SharedWorker")}}</dt> + <dd>Represents a specific kind of worker that can be <em>accessed</em> from several browsing contexts, being several windows, iframes or even workers.</dd> + <dt>{{domxref("WorkerGlobalScope")}}</dt> + <dd>Represents the generic scope of any worker (doing the same job as {{domxref("Window")}} does for normal web content). Different types of worker have scope objects that inherit from this interface and add more specific features.</dd> + <dt>{{domxref("DedicatedWorkerGlobalScope")}}</dt> + <dd>Represents the scope of a dedicated worker, inheriting from {{domxref("WorkerGlobalScope")}} and adding some dedicated features.</dd> + <dt>{{domxref("SharedWorkerGlobalScope")}}</dt> + <dd>Represents the scope of a shared worker, inheriting from {{domxref("WorkerGlobalScope")}} and adding some dedicated features.</dd> + <dt>{{domxref("WorkerNavigator")}}</dt> + <dd>Represents the identity and state of the user agent (the client):</dd> +</dl> + +<h2 id="Examples">Examples</h2> + +<p>We have created a couple of simple demos to show basic usage:</p> + +<ul> + <li><a href="https://github.com/mdn/simple-web-worker">Basic dedicated worker example</a> (<a href="http://mdn.github.io/simple-web-worker/">run dedicated worker</a>).</li> + <li><a href="https://github.com/mdn/simple-shared-worker">Basic shared worker example</a> (<a href="http://mdn.github.io/simple-shared-worker/">run shared worker</a>).</li> +</ul> + +<p>You can find out more information on how these demos work in <a href="/en-US/docs/Web/API/Web_Workers_API/Using_web_workers">Using web workers</a>.</p> + +<h2 id="Specifications">Specifications</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('HTML WHATWG', '#toc-workers')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>No change from {{SpecName("Web Workers")}}.</td> + </tr> + <tr> + <td>{{SpecName('Web Workers')}}</td> + <td>{{Spec2('Web Workers')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>4</td> + <td>{{CompatGeckoDesktop(1.9.1)}}</td> + <td>10.0</td> + <td>10.6</td> + <td>4</td> + </tr> + <tr> + <td>Shared workers</td> + <td>4</td> + <td>{{CompatGeckoDesktop(29)}}</td> + <td>{{CompatNo}}</td> + <td>10.6</td> + <td>4</td> + </tr> + <tr> + <td>Passing data using structured cloning</td> + <td>13</td> + <td>{{CompatGeckoDesktop(8)}}</td> + <td>10.0</td> + <td>11.5</td> + <td>6</td> + </tr> + <tr> + <td>Passing data using transferable objects</td> + <td>17 {{property_prefix("webkit")}}<br> + 21</td> + <td>{{CompatGeckoDesktop(18)}}</td> + <td>{{CompatNo}}</td> + <td>15</td> + <td>6</td> + </tr> + <tr> + <td>Global {{domxref("window.URL", "URL")}}</td> + <td>10<sup>[1]</sup><br> + 23</td> + <td>{{CompatGeckoDesktop(21)}}</td> + <td>11</td> + <td>15</td> + <td>6<sup>[1]</sup></td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>4.4</td> + <td>4</td> + <td>{{CompatGeckoMobile(1.9.1)}}</td> + <td>1.0.1</td> + <td>10.0</td> + <td>11.5</td> + <td>5.1</td> + </tr> + <tr> + <td>Shared workers</td> + <td>{{CompatNo}}</td> + <td>4</td> + <td>29</td> + <td>1.4</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>Passing data using structured cloning</td> + <td>{{CompatNo}}</td> + <td>4</td> + <td>8</td> + <td>1.0.1</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>Passing data using transferable objects</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>18</td> + <td>1.0.1</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] As <code>webkitURL</code>.</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/Web_Workers_API/basic_usage">Using Web Workers</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/Worker">Worker Interface</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker">SharedWorker interface</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorker_API">ServiceWorker API</a></li> + <li><a href="/en-US/docs/Web/API/Worker/Functions_and_classes_available_to_workers">Functions and classes available to workers</a></li> + <li><a href="/en-US/docs/Web/API/Web_Workers_API/Advanced_concepts_and_examples">Advanced concepts and examples</a></li> + <li><a href="/en-US/docs/Web/API/ChromeWorker">ChromeWorker</a>: for using workers in privileged/chrome code</li> +</ul> diff --git a/files/zh-tw/web/api/web_workers_api/using_web_workers/index.html b/files/zh-tw/web/api/web_workers_api/using_web_workers/index.html new file mode 100644 index 0000000000..82d484f6a2 --- /dev/null +++ b/files/zh-tw/web/api/web_workers_api/using_web_workers/index.html @@ -0,0 +1,791 @@ +--- +title: 使用 Web Workers +slug: Web/API/Web_Workers_API/Using_web_workers +translation_of: Web/API/Web_Workers_API/Using_web_workers +--- +<div class="summary"> +<p><span style="line-height: inherit;">Web Workers 提供簡單的方法讓網頁在背景執行緒 (Thread) 中執行程式，而不干擾使用者介面運行</span>，<span style="line-height: inherit;">另外，Worker也可以利用 </span><a href="https://developer.mozilla.org/en/nsIXMLHttpRequest" style="line-height: inherit;" title="https://developer.mozilla.org/en/nsIXMLHttpRequest">XMLHttpRequest</a><span style="line-height: inherit;"> 執行輸出/輸入(但是responseXML 和channel這兩個屬性為null)</span>；<span style="line-height: inherit;">一個worker可以藉由事件處理器來和</span> <span style="line-height: inherit;">web worker 創造端互相傳送訊息</span>，接下來本文會提供使用 web worker 的詳細說明。</p> +</div> + +<h2 id="Web_Workers_API">Web Workers API</h2> + +<p>透過 worker 建構子 (如 {{domxref("Worker.Worker", "Worker()")}}) 便可以產生 worker 物件，並且執行 JavaScript 檔案。在 worker 中的 JavaScript 運行在不同於 {{domxref("window")}} 的執行緒環境，所以在 worker 中存取全域物件應該要透過 {{domxref("window.self","self")}}，如果透過 {{domxref("window")}} 會導致錯誤發生。</p> + +<p>Dedicated worker (專有 worker) 是一般 worker，只能被產生它的檔案存取，{{domxref("DedicatedWorkerGlobalScope")}} 物件代表其執行環境；而Shared worker (共享 worker) 則能夠被不同檔案存取，{{domxref("SharedWorkerGlobalScope")}}) 物件代表其執行環境。</p> + +<div class="note"> +<p><strong>Note</strong>: worker 其他文件說明請見 <a href="/en-US/docs/Web/API/Web_Workers_API">The Web Workers API landing page</a> 。</p> +</div> + +<p>基本上 worker 能夠執行任何事情，比如說 <a href="/en-US/docs/Web/API/WebSockets_API">WebSockets</a>、<a href="/en-US/docs/Web/API/IndexedDB_API">IndexedDB</a>、和 Firefox OS 特有的 <a href="/en-US/docs/Web/API/Data_Store_API">Data Store API</a> ，然而直接存取 DOM 或是 {{domxref("window")}} 物件的一些方法和屬性則不被允許，更多細節請見 <a href="/en-US/docs/Web/API/Worker/Functions_and_classes_available_to_workers">worker 可存取知函數和類別</a>。</p> + +<p>主執行緒和 worker 執行緒之間用 postMessage() 方法發送訊息，然後透過 <code>onmessage</code> 事件接受訊息 (訊息存在 {{event("Message")}} 事件的 data 屬性之中)，其中被傳送的資料並非共享而是複製一份後傳送。</p> + +<p>worker 可以產生新 worker，只要新 worker 的來源 (origin) 和父頁面相同，<span style="line-height: inherit;">也可以利用 </span><a href="https://developer.mozilla.org/en/nsIXMLHttpRequest" style="line-height: inherit;" title="https://developer.mozilla.org/en/nsIXMLHttpRequest">XMLHttpRequest</a> <span style="line-height: inherit;">執行輸出/輸入(但是responseXML 和channel這兩個屬性為null)。</span></p> + +<h2 id="Dedicated_workers">Dedicated workers</h2> + +<p>dedicated worker 只能被產生它的檔案存取，下面我們先介紹簡單的 <a class="external external-icon" href="https://github.com/mdn/simple-web-worker">Basic dedicated worker example</a> (<a class="external external-icon" href="http://mdn.github.io/simple-web-worker/">run dedicated worker</a>) 範例。這個範例會將兩個數字送入 worker 相乘，然後再於前端頁面顯示相乘結果。</p> + +<h3 id="偵測_Worker_功能">偵測 Worker 功能</h3> + +<p>為了向下相容、避免錯誤，最好是確保 worker 存在後再取用之 (<a href="https://github.com/mdn/simple-web-worker/blob/gh-pages/main.js">main.js</a>):</p> + +<pre class="brush: js">if (window.Worker) { + + ... + +}</pre> + +<h3 id="產生_dedicated_worker">產生 dedicated worker</h3> + +<p>只要呼叫 {{domxref("Worker.Worker", "Worker()")}} 建構子，傳入 JS 檔案的 URI，便可以生成一個 worker 執行緒 (<a href="https://github.com/mdn/simple-web-worker/blob/gh-pages/main.js">main.js</a>):</p> + +<div style="overflow: hidden;"> +<pre class="brush: js">var myWorker = new Worker("worker.js"); +</pre> +</div> + +<h3 id="和_dedicated_worker_發送訊息">和 dedicated worker 發送訊息</h3> + +<p>{{domxref("Worker.postMessage", "postMessage()")}} 方法以及 {{domxref("Worker.onmessage", "onmessage")}} 事件處理器就是和 worker 發送訊息的關鍵 (<a href="https://github.com/mdn/simple-web-worker/blob/gh-pages/main.js">main.js</a>):</p> + +<pre class="brush: js">first.onchange = function() { + myWorker.postMessage([first.value,second.value]); + console.log('Message posted to worker'); +} + +second.onchange = function() { + myWorker.postMessage([first.value,second.value]); + console.log('Message posted to worker'); +}</pre> + +<p>範例中有兩個 {{htmlelement("input")}} 元素，first 和 second，當元素值改變時，我們會利用 postMessage() 方法告訴 worker 改變的值 (這邊用陣列，也可以用其他類別)。</p> + +<p>然後在 worker 裡我們從 <code>onmessage</code> 接收訊息 (<a href="https://github.com/mdn/simple-web-worker/blob/gh-pages/worker.js">worker.js</a>):</p> + +<pre class="brush: js">onmessage = function(e) { + console.log('Message received from main script'); + var workerResult = 'Result: ' + (e.data[0] * e.data[1]); + console.log('Posting message back to main script'); + postMessage(workerResult); +}</pre> + +<p><code>onmessage</code> 事件物件的 data 屬性存有傳送過來的訊息資料，也就是 input 值；worker 收到後將傳過來的兩個值相乘，再 postMessage 傳回去。</p> + +<p>回到主執行，同樣透過<code> onmessage</code> 事件，收到 worker 回傳還來的計算值 :</p> + +<pre class="brush: js">myWorker.onmessage = function(e) { + result.textContent = e.data; + console.log('Message received from worker'); +}</pre> + +<p>拿到存在事件 data 中的計算值後，我們接著將值以<code> textContent</code> 顯示出來。</p> + +<div class="note"> +<p><strong>Note</strong> : <code>建構 Worker</code> 的URI必須遵從<a href="/en-US/docs/Web/Security/Same-origin_policy"> same-origin policy</a>。目前各家瀏覽器在這方面存有歧異，Gecko 10.0 {{geckoRelease("10.0")}} 以後允許 data URI 而 Internet Explorer 10 不允許 Blob URI。</p> +</div> + +<div class="note"><strong>Note</strong>: 在主執行緒中存取 <code>onmessage</code> <code>與 postMessage</code> 需要主動掛在 worker 物件上，在 worker 執行緒則不用，這是因為 worker 執行緒的全域物件便是 worker 物件。</div> + +<div class="note"><strong>Note</strong>: 和 worker 傳送的資料並非共享而是複製一份後傳送，詳細請參照 {{anch("Transferring data to and from workers: further details")}}。</div> + +<h3 id="結束_worker">結束 worker</h3> + +<p><code>在主執行緒裡呼叫</code> {{domxref("Worker", "terminate")}} 就可結束 worker :</p> + +<pre class="brush: js">myWorker.terminate();</pre> + +<p>請注意不論 worker 正在執行的運算完成與否，一但呼叫後 worker 便會立刻被終止。</p> + +<p>而在 worker 執行緒裡，worker 可以呼叫自己的 {{domxref("WorkerGlobalScope", "close")}} 方法來結束 :</p> + +<pre class="brush: js">close();</pre> + +<h3 id="錯誤處理">錯誤處理</h3> + +<p>當執行時期錯誤發生時，onerror 事件處理器會被呼叫，onerror事件處理器會收到一名為 error 的事件物件 (實作 ErrorEvent Interface)，該事件不會 bubble 且可取消，如果要避免事件預設行為，可以呼叫 <a class="internal" href="/en-US/docs/Web/API/Event/preventDefault"><code>preventDefault()</code></a>。</p> + +<p>以下三個部分是錯誤事件較關鍵的地方:</p> + +<dl> + <dt><code>message</code></dt> + <dd>供人閱讀的錯誤訊息</dd> + <dt><code>filename</code></dt> + <dd>錯誤發生所在的檔案名稱</dd> + <dt><code>lineno</code></dt> + <dd>錯誤發生所在的行數</dd> +</dl> + +<h3 id="產生_subworker"><span style="line-height: inherit;">產生</span> subworker</h3> + +<p><span style="line-height: inherit;">worker 可以產生其他 worker (subworker)，subworker </span><span style="line-height: inherit;">的來源</span><span style="line-height: inherit;">也必須和主頁相同，另外，subworker 的 URI 的解析是相對於父 worker 的位置而非所在頁面，這項特色有助於追蹤 worker 間的相依性。</span></p> + +<h3 id="引入程式腳本與函式庫_(library)">引入程式腳本與函式庫 (library)</h3> + +<p>Worker執行緒能存取一個全域函數 (global function), importScripts()。importScripts() 可以讓 worker 端引入相同網域的程式碼腳本與 libraries，importScripts()可接收零到數個要被輸入資源的URI，底下為幾個範例:</p> + +<pre class="brush: js">importScripts(); /* imports nothing */ +importScripts('foo.js'); /* imports just "foo.js" */ +importScripts('foo.js', 'bar.js'); /* imports two scripts */ +</pre> + +<p>瀏覽器會載入並執行每個程式碼腳本，然後 worker 能夠存取程式碼腳本內定義的全域變數，若是腳本無法載入，會產生一個 NETWORK_ERROR，後續的程式碼不會被執行，但是先前執行過的程式碼或用 <a href="https://developer.mozilla.org/en-US/docs/Web/API/window.setTimeout" title="https://developer.mozilla.org/en-US/docs/Web/API/window.setTimeout">window.setTimeout()</a> 延遲執行的程式碼依然有效，而 importScripts() 之後宣告的函數也一樣存在，因為這些程式碼總是在其他程式碼之前就解析過了。</p> + +<div class="note"><strong>Note:</strong> <span style="color: #333333; line-height: inherit;">雖然程式碼腳本的下載順序不一定，但執行順序會遵照傳入importScripts()的順序，這是同步完成的，importScripts()不會回傳直到所有的程式碼都下載並執行完。</span></div> + +<h2 id="Shared_workers">Shared workers</h2> + +<p>shared worker 能夠被多個程式腳本存取，縱使跨越不同 window、iframe 或 worker。這邊的 <a class="external external-icon" href="https://github.com/mdn/simple-shared-worker">Basic shared worker example</a> (<a class="external external-icon" href="http://mdn.github.io/simple-shared-worker/">run shared worker</a>) 範例和 dedicated worker 範例類似，但多了兩個可以讓多個檔案存取的函數：<em>數字相乘以及數字平方</em>。</p> + +<p>請注意 dedicated worker 與 shared worker 間的差異處，範例裡會有兩份 HTML 頁面，各自都利用同一個 worker 處理運算。</p> + +<div class="note"> +<p><strong>Note:</strong> 所有的瀏覽環境都必需共享相同的來源（相同protocol, host 和 port），shared worker 才能讓不同瀏覽環境存取。</p> +</div> + +<div class="note"> +<p><strong>Note</strong>: 在 Firefox， shared worker 無法在一般和隱私模式間共享 ({{bug(1177621)}})。</p> +</div> + +<h3 id="產生_shared_worker">產生 shared worker</h3> + +<p>和 dedicated worker 做法差不多，只是用另一個 SharedWorker 建構子來產生 shared worker，見 <a href="https://github.com/mdn/simple-shared-worker/blob/gh-pages/index.html">index.html</a> 和 <a href="http://mdn.github.io/simple-shared-worker/index2.html">index2.html</a>:</p> + +<pre class="brush: js">var myWorker = new SharedWorker("worker.js");</pre> + +<p>相當不 一樣的是和 shared worker 溝通必須要透過 port 物件，其實 dedicated worker 也是如此，只不過一切是在背景後自動完成。</p> + +<p>開啟 port 連線一是在 onmessage 事件下背景完成，二是藉由主動呼叫 start() 好開始傳送訊息。範例<a href="https://github.com/mdn/simple-shared-worker/blob/gh-pages/multiply.js"> multiply.js</a> 以及 <a href="https://github.com/mdn/simple-shared-worker/blob/gh-pages/worker.js">worker.js</a> 因為註冊了 onmessage 事件，所以其實可以省略呼叫 start()，然而若是 message 事件是經由 <code>addEventListener()註冊，那麼便需要呼叫 start() 了。</code></p> + +<p>當使用 start() 開啟 port 連線，那麼雙向溝通便需要主執行緒和 worker 兩端都呼叫 start()。</p> + +<pre class="brush: js">myWorker.port.start(); // called in parent thread</pre> + +<pre class="brush: js">port.start(); // called in worker thread, assuming the <code>port</code> variable references a port</pre> + +<h3 id="和_shared_worker_發送訊息">和 shared worker 發送訊息</h3> + +<p>如同前面，現在可以呼叫 <code>postMessage()</code> 發送訊息，只不過這次需要透過 port 物件 (一樣請參考 <a href="https://github.com/mdn/simple-shared-worker/blob/gh-pages/multiply.js">multiply.js</a> 和 <a href="https://github.com/mdn/simple-shared-worker/blob/gh-pages/square.js">square.js</a>):</p> + +<pre class="brush: js">squareNumber.onchange = function() { + myWorker.port.postMessage([squareNumber.value,squareNumber.value]); + console.log('Message posted to worker'); +}</pre> + +<p>worker 方面也增加了一些程式碼 (<a href="https://github.com/mdn/simple-shared-worker/blob/gh-pages/worker.js">worker.js</a>):</p> + +<pre class="brush: js">onconnect = function(e) { + var port = e.ports[0]; + port.onmessage = function(e) { + var workerResult = 'Result: ' + (e.data[0] * e.data[1]); + port.postMessage(workerResult); + } + <s>port.start();</s> // not necessary since onmessage event handler is being used +}</pre> + +<p>首先，先監聽連線建立的 onconnect 事件，例如當主執行緒建立 onmessage 事件或呼叫 <code>start()</code>。</p> + +<p>然後從 onconnect 事件物件，我們可以取得 port 物件使用之。</p> + +<p>取得 port 之後，我們註冊 port 上的 onmessage 事件，當有訊息進來便取回資料進行運算後回傳回去；註冊 onmessage 事件的同時也自動建立連線，所以說不需要呼叫start() 了。</p> + +<p>最後在主執行緒端，我們同樣由 onmessage 事件取回回傳過來的訊息 (一樣請參考 <a href="https://github.com/mdn/simple-shared-worker/blob/gh-pages/multiply.js">multiply.js</a> 和 <a href="https://github.com/mdn/simple-shared-worker/blob/gh-pages/square.js">square.js</a>):</p> + +<pre class="brush: js">myWorker.port.onmessage = function(e) { + result2.textContent = e.data[0]; + console.log('Message received from worker'); +}</pre> + +<p> </p> + +<h2 id="執行緒_(Thread)_安全">執行緒 (Thread) 安全</h2> + +<p>{{domxref("Worker")}} 會產生真正 OS 層級的執行緒，細心的開發者或許會擔心同步問題。</p> + +<p>不過 worker 會十分注意和其他執行緒溝通的狀況，不會去存取非執行緒安全的元件，如 DOM ，而且資料的傳遞也都序列化 (serialized) ，所以說很難會發生同步問題。</p> + +<h2 id="和_workers_傳遞資料：更多細節">和 workers 傳遞資料：更多細節</h2> + +<p>和 workers 傳遞的資料會先被複製一份，而非共享；經過序列化後 (serialized) 傳輸，然後在另一端反序列化 (de-serialized) 取出，大部份的瀏覽器都是以 <a href="/en-US/docs/Web/Guide/API/DOM/The_structured_clone_algorithm">結構化複製 (structured cloning)</a> 實作這項特色.</p> + +<p>下面的 <code>emulateMessage() 會模擬和 worker 傳遞訊息時，複製資料的行為。</code></p> + +<pre class="brush: js">function emulateMessage (vVal) { + return eval("(" + JSON.stringify(vVal) + ")"); +} + +// Tests + +// test #1 +var example1 = new Number(3); +console.log(typeof example1); // object +console.log(typeof emulateMessage(example1)); // number + +// test #2 +var example2 = true; +console.log(typeof example2); // boolean +console.log(typeof emulateMessage(example2)); // boolean + +// test #3 +var example3 = new String("Hello World"); +console.log(typeof example3); // object +console.log(typeof emulateMessage(example3)); // string + +// test #4 +var example4 = { + "name": "John Smith", + "age": 43 +}; +console.log(typeof example4); // object +console.log(typeof emulateMessage(example4)); // object + +// test #5 +function Animal (sType, nAge) { + this.type = sType; + this.age = nAge; +} +var example5 = new Animal("Cat", 3); +alert(example5.constructor); // Animal +alert(emulateMessage(example5).constructor); // Object</pre> + +<p>所謂的訊息就是經過複製、非共享的資料，到這邊你應該已經知道 <code>postMessage()</code> 負責發送訊息，然後 <code>message</code> 事件 {{domxref("MessageEvent.data", "data")}} 的 attribute 則存有傳送的訊息資料。</p> + +<p><strong>example.html</strong>: (the main page):</p> + +<pre class="brush: js">var myWorker = new Worker("my_task.js"); + +myWorker.onmessage = function (oEvent) { + console.log("Worker said : " + oEvent.data); +}; + +myWorker.postMessage("ali");</pre> + +<p><strong>my_task.js</strong> (the worker):</p> + +<pre class="brush: js">postMessage("I\'m working before postMessage(\'ali\')."); + +onmessage = function (oEvent) { + postMessage("Hi " + oEvent.data); +};</pre> + +<p><a href="/en-US/docs/Web/Guide/API/DOM/The_structured_clone_algorithm">結構化複製（structured cloning）</a> 演算法支援 JSON 以及迴圈參照（circular references）。</p> + +<h3 id="資料傳遞範例">資料傳遞範例</h3> + +<h4 id="範例_1_非同步_eval()">範例 1: 非同步 <code>eval()</code></h4> + +<p>下面透過 <a href="/en-US/docs/Web/HTTP/data_URIs">data URL</a> 和 <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval">eval()</a>，</code>示範如何在 worker 非同步執行允許的程式碼：</p> + +<pre class="brush: js">// Syntax: asyncEval(code[, listener]) + +var asyncEval = (function () { + var aListeners = [], oParser = new Worker("data:text/javascript;charset=US-ASCII,onmessage%20%3D%20function%20%28oEvent%29%20%7B%0A%09postMessage%28%7B%0A%09%09%22id%22%3A%20oEvent.data.id%2C%0A%09%09%22evaluated%22%3A%20eval%28oEvent.data.code%29%0A%09%7D%29%3B%0A%7D"); + + oParser.onmessage = function (oEvent) { + if (aListeners[oEvent.data.id]) { aListeners[oEvent.data.id](oEvent.data.evaluated); } + delete aListeners[oEvent.data.id]; + }; + + return function (sCode, fListener) { + aListeners.push(fListener || null); + oParser.postMessage({ + "id": aListeners.length - 1, + "code": sCode + }); + }; +})();</pre> + +<p><a href="en-US/docs/Web/HTTP/data_URIs">data URL</a> 相當於網路請求，範例中的 data URL 會在 worker 執行下列程式碼回應訊息：</p> + +<pre class="brush: js">onmessage = function (oEvent) { + postMessage({ + "id": oEvent.data.id, + "evaluated": eval(oEvent.data.code) + }); +}</pre> + +<p>應用範例:</p> + +<pre class="brush: js">// asynchronous alert message... +asyncEval("3 + 2", function (sMessage) { + alert("3 + 2 = " + sMessage); +}); + +// asynchronous print message... +asyncEval("\"Hello World!!!\"", function (sHTML) { + document.body.appendChild(document.createTextNode(sHTML)); +}); + +// asynchronous void... +asyncEval("(function () {\n\tvar oReq = new XMLHttpRequest();\n\toReq.open(\"get\", \"http://www.mozilla.org/\", false);\n\toReq.send(null);\n\treturn oReq.responseText;\n})()");</pre> + +<h4 id="範例2_JSON_資料進階傳遞與呼叫系統">範例2: JSON 資料進階傳遞與呼叫系統</h4> + +<p>下面的範例系統適合需要在主頁面和 worker 傳遞複雜資料和呼叫多個函數的情境。</p> + +<p><strong>example.html</strong> (主頁面):</p> + +<pre class="brush: html"><!doctype html> +<html> +<head> +<meta charset="UTF-8" /> +<title>MDN Example - Queryable worker</title> +<script type="text/javascript"> + /* + QueryableWorker instances methods: + * sendQuery(queryable function name, argument to pass 1, argument to pass 2, etc. etc): calls a Worker's queryable function + * postMessage(string or JSON Data): see Worker.prototype.postMessage() + * terminate(): terminates the Worker + * addListener(name, function): adds a listener + * removeListener(name): removes a listener + QueryableWorker instances properties: + * defaultListener: the default listener executed only when the Worker calls the postMessage() function directly + */ + function QueryableWorker (sURL, fDefListener, fOnError) { + var oInstance = this, oWorker = new Worker(sURL), oListeners = {}; + this.defaultListener = fDefListener || function () {}; + oWorker.onmessage = function (oEvent) { + if (oEvent.data instanceof Object && oEvent.data.hasOwnProperty("vo42t30") && oEvent.data.hasOwnProperty("rnb93qh")) { + oListeners[oEvent.data.vo42t30].apply(oInstance, oEvent.data.rnb93qh); + } else { + this.defaultListener.call(oInstance, oEvent.data); + } + }; + if (fOnError) { oWorker.onerror = fOnError; } + this.sendQuery = function (/* queryable function name, argument to pass 1, argument to pass 2, etc. etc */) { + if (arguments.length < 1) { throw new TypeError("QueryableWorker.sendQuery - not enough arguments"); return; } + oWorker.postMessage({ "bk4e1h0": arguments[0], "ktp3fm1": Array.prototype.slice.call(arguments, 1) }); + }; + this.postMessage = function (vMsg) { + //I just think there is no need to use call() method + //how about just oWorker.postMessage(vMsg); + //the same situation with terminate + //well,just a little faster,no search up the prototye chain + Worker.prototype.postMessage.call(oWorker, vMsg); + }; + this.terminate = function () { + Worker.prototype.terminate.call(oWorker); + }; + this.addListener = function (sName, fListener) { + oListeners[sName] = fListener; + }; + this.removeListener = function (sName) { + delete oListeners[sName]; + }; + }; + + // your custom "queryable" worker + var oMyTask = new QueryableWorker("my_task.js" /* , yourDefaultMessageListenerHere [optional], yourErrorListenerHere [optional] */); + + // your custom "listeners" + + oMyTask.addListener("printSomething", function (nResult) { + document.getElementById("firstLink").parentNode.appendChild(document.createTextNode(" The difference is " + nResult + "!")); + }); + + oMyTask.addListener("alertSomething", function (nDeltaT, sUnit) { + alert("Worker waited for " + nDeltaT + " " + sUnit + " :-)"); + }); +</script> +</head> +<body> + <ul> + <li><a id="firstLink" href="javascript:oMyTask.sendQuery('getDifference', 5, 3);">What is the difference between 5 and 3?</a></li> + <li><a href="javascript:oMyTask.sendQuery('waitSomething');">Wait 3 seconds</a></li> + <li><a href="javascript:oMyTask.terminate();">terminate() the Worker</a></li> + </ul> +</body> +</html></pre> + +<p><strong>my_task.js</strong> (worker):</p> + +<pre class="brush: js">// your custom PRIVATE functions + +function myPrivateFunc1 () { + // do something +} + +function myPrivateFunc2 () { + // do something +} + +// etc. etc. + +// your custom PUBLIC functions (i.e. queryable from the main page) + +var queryableFunctions = { + // example #1: get the difference between two numbers: + getDifference: function (nMinuend, nSubtrahend) { + reply("printSomething", nMinuend - nSubtrahend); + }, + // example #2: wait three seconds + waitSomething: function () { + setTimeout(function() { reply("alertSomething", 3, "seconds"); }, 3000); + } +}; + +// system functions + +function defaultQuery (vMsg) { + // your default PUBLIC function executed only when main page calls the queryableWorker.postMessage() method directly + // do something +} + +function reply (/* listener name, argument to pass 1, argument to pass 2, etc. etc */) { + if (arguments.length < 1) { throw new TypeError("reply - not enough arguments"); return; } + postMessage({ "vo42t30": arguments[0], "rnb93qh": Array.prototype.slice.call(arguments, 1) }); +} + +onmessage = function (oEvent) { + if (oEvent.data instanceof Object && oEvent.data.hasOwnProperty("bk4e1h0") && oEvent.data.hasOwnProperty("ktp3fm1")) { + queryableFunctions[oEvent.data.bk4e1h0].apply(self, oEvent.data.ktp3fm1); + } else { + defaultQuery(oEvent.data); + } +}; +</pre> + +<h3 id="移轉資料所有權_-_可移轉物件_(transferable_objects)">移轉資料所有權 - 可移轉物件 (transferable objects)</h3> + +<p>Google Chrome 17+ 以及 Firefox 18+ 能夠和 worker 高效能地傳送另外一種特定型態物件 (可移轉物件, transferable objects，這種物件實作了 {{domxref("Transferable")}} 介面)，可移轉物件當被傳送到另一端時並不需要複製，因此可以大大提升傳送大型資料物件的效能；這好比像是 C/C++ 的 pass-by-reference，但是不同的是，一旦移轉後原先的環境便失去了持有資料，例如當主頁面傳送 {{domxref("ArrayBuffer")}} 後，主頁面便不再能夠使用這筆資料物件了，這筆資料物件的存取連結已經靜靜地移轉到 worker 端了。</p> + +<pre class="brush: js">// Create a 32MB "file" and fill it. +var uInt8Array = new Uint8Array(1024*1024*32); // 32MB +for (var i = 0; i < uInt8Array.length; ++i) { + uInt8Array[i] = i; +} + +worker.postMessage(uInt8Array.buffer, [uInt8Array.buffer]); +</pre> + +<div class="note"> +<p><strong>Note</strong>: 關於更多可移轉物件的資訊, 效能和功能偵測，請參考 HTML5 Rocks 上 <a href="http://updates.html5rocks.com/2011/12/Transferable-Objects-Lightning-Fast">Transferable Objects: Lightning Fast!</a> 一文。</p> +</div> + +<h2 id="Embedded_workers">Embedded workers</h2> + +<p>不像 {{HTMLElement("script")}}，並沒有一套正式標準的方法將 worker 的程式碼嵌入到頁面之中，不過沒有 src 屬性而且 mime-type 不屬於可執行程式碼的 {{HTMLElement("script")}} 元素會被視為 javascript 可以取用的資料區塊（data block），資料區塊是一項 HTML5 可用於攜帶文字資料的特色功能，利用資料區塊我們就有辦法嵌入 worker 的程式碼到頁面中：</p> + +<pre class="brush: html"><!DOCTYPE html> +<html> +<head> +<meta charset="UTF-8" /> +<title>MDN Example - Embedded worker</title> +<script type="text/js-worker"> + // This script WON'T be parsed by JS engines because its mime-type is text/js-worker. + var myVar = "Hello World!"; + // Rest of your worker code goes here. +</script> +<script type="text/javascript"> + // This script WILL be parsed by JS engines because its mime-type is text/javascript. + function pageLog (sMsg) { + // Use a fragment: browser will only render/reflow once. + var oFragm = document.createDocumentFragment(); + oFragm.appendChild(document.createTextNode(sMsg)); + oFragm.appendChild(document.createElement("br")); + document.querySelector("#logDisplay").appendChild(oFragm); + } +</script> +<script type="text/js-worker"> + // This script WON'T be parsed by JS engines because its mime-type is text/js-worker. + onmessage = function (oEvent) { + postMessage(myVar); + }; + // Rest of your worker code goes here. +</script> +<script type="text/javascript"> + // This script WILL be parsed by JS engines because its mime-type is text/javascript. + + // In the past...: + // blob builder existed + // ...but now we use Blob...: + var blob = new Blob(Array.prototype.map.call(document.querySelectorAll("script[type=\"text\/js-worker\"]"), function (oScript) { return oScript.textContent; }),{type: "text/javascript"}); + + // Creating a new document.worker property containing all our "text/js-worker" scripts. + document.worker = new Worker(window.URL.createObjectURL(blob)); + + document.worker.onmessage = function (oEvent) { + pageLog("Received: " + oEvent.data); + }; + + // Start the worker. + window.onload = function() { document.worker.postMessage(""); }; +</script> +</head> +<body><div id="logDisplay"></div></body> +</html></pre> + +<p>Embedded worker 在 <code>document.worker</code> 之中。</p> + +<h2 id="其他範例">其他範例</h2> + +<p>下面介紹其他使用 worker 的範例。</p> + +<h3 id="在背景中執行運算">在背景中執行運算</h3> + +<p>worker 主要的用處在避免重度 CPU 運算的任務阻礙到 UI 執行緒運行；這邊我們用 worker 來跑 Fibonacci 數列運算。</p> + +<h4 id="JavaScript">JavaScript</h4> + +<p>fibonacci.js 中的程式碼會被另一份 HTML 引用。</p> + +<pre class="brush: js">var results = []; + +function resultReceiver(event) { + results.push(parseInt(event.data)); + if (results.length == 2) { + postMessage(results[0] + results[1]); + } +} + +function errorReceiver(event) { + throw event.data; +} + +onmessage = function(event) { + var n = parseInt(event.data); + + if (n == 0 || n == 1) { + postMessage(n); + return; + } + + for (var i = 1; i <= 2; i++) { + var worker = new Worker("fibonacci.js"); + worker.onmessage = resultReceiver; + worker.onerror = errorReceiver; + worker.postMessage(n - i); + } + };</pre> + +<p>worker 程式碼中註冊了一個 <code>onmessage</code> 事件處理器用來接收另一端 <code>postMessage 過來的訊息</code> (請注意這並非定義一個全域變數或函數，<code>var onmessage</code> 或 <code>function onmessage</code> 會定義全域變數，但不會註冊事件處理器)，然後開始進行遞迴運算。</p> + +<h4 id="HTML">HTML</h4> + +<pre class="brush: html"><!DOCTYPE html> +<html> + <head> + <meta charset="UTF-8" /> + <title>Test threads fibonacci</title> + </head> + <body> + + <div id="result"></div> + + <script language="javascript"> + + var worker = new Worker("fibonacci.js"); + + worker.onmessage = function(event) { + document.getElementById("result").textContent = event.data; + dump("Got: " + event.data + "\n"); + }; + + worker.onerror = function(error) { + dump("Worker error: " + error.message + "\n"); + throw error; + }; + + worker.postMessage("5"); + + </script> + </body> +</html> +</pre> + +<p>onmessage 事件處理器會接收 worker 回傳的運算結果，然後顯示在頁面上，如果有問題， onerror 事件處理器會 <a href="/en-US/docs/Debugging_JavaScript#dump.28.29">輸出</a> 錯誤訊息。</p> + +<p>和 worker 溝通則是利用 postMessage。</p> + +<p><a class="external" href="/samples/workers/fibonacci">範例測試</a>。</p> + +<h3 id="在背景中執行_web_IO">在背景中執行 web I/O</h3> + +<p>範例請見 <a class="internal" href="/en-US/docs/Using_workers_in_extensions">Using workers in extensions</a> 。</p> + +<h3 id="分割任務到多個_workers">分割任務到多個 workers</h3> + +<p>基於多核 cpu 的普及，分割複雜任務到多個 workers 將可能有助於利用多核心 cpu 的優勢。</p> + +<h2 id="其他類型的_worker">其他類型的 worker</h2> + +<p>除了 dedicated 和 shared web workers，還有其他種類：</p> + +<ul> + <li><a href="/en-US/docs/Web/API/ServiceWorker_API">ServiceWorkers</a> 基本上如同介於 web app 和瀏覽器以及網路之間的代理伺服器 (proxy server)，這類 worker 重點在實現離線服務，service worker 會攔截網路請求，然後依據網路連線和資源狀態做出反應，他們可以存取推播和背景同步 APIs。</li> + <li>Chrome Workers 是 Firefox 唯一的 worker 類型，他們可以用在開發 add-ons，或是想要使用 <a href="https://developer.mozilla.org/en/js-ctypes">js-ctypes</a>。詳情請見 {{domxref("ChromeWorker")}}。</li> + <li><a href="/en-US/docs/Web/API/Web_Audio_API#Audio_Workers">Audio Workers</a> 主要用於音效處理部分。</li> +</ul> + +<h2 id="Worker_可存取之函數與介面">Worker 可存取之函數與介面</h2> + +<p>大多數 Javascript 的功能 workre 皆可以使用，包含：</p> + +<ul> + <li>{{domxref("Navigator")}}</li> + <li>{{domxref("XMLHttpRequest")}}</li> + <li>{{jsxref("Global_Objects/Array", "Array")}}, {{jsxref("Global_Objects/Date", "Date")}}, {{jsxref("Global_Objects/Math", "Math")}}, 與 {{jsxref("Global_Objects/String", "String")}}</li> + <li>{{domxref("Window.requestAnimationFrame")}}, {{domxref("WindowTimers.setTimeout")}}, 與 {{domxref("WindowTimers.setInterval")}}</li> +</ul> + +<p>worker 無法操作主頁面的物件與 DOM，如有相關需求，必須要間接透過 {{domxref("DedicatedWorkerGlobalScope.postMessage")}} 通知主頁面，讓主頁面執行需求。</p> + +<div class="note"> +<p><strong>Note</strong>: 所有 worker 可存取功能一覽表，請見 <a href="/en-US/docs/Web/Reference/Functions_and_classes_available_to_workers">Functions and interfaces available to workers</a>.</p> +</div> + +<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('HTML WHATWG', '#toc-workers')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>No change from {{SpecName("Web Workers")}}.</td> + </tr> + <tr> + <td>{{SpecName('Web Workers')}}</td> + <td>{{Spec2('Web Workers')}}</td> + <td>Initial definition.</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>4<sup>[1]</sup></td> + <td>{{CompatGeckoDesktop("1.9.1")}}</td> + <td>10.0</td> + <td>10.6<sup>[1]</sup></td> + <td>4<sup>[2]</sup></td> + </tr> + <tr> + <td>Shared workers</td> + <td>4<sup>[1]</sup></td> + <td>{{CompatGeckoDesktop(29)}}</td> + <td>{{CompatNo}}</td> + <td>10.6</td> + <td>4<sup>[2]</sup></td> + </tr> + <tr> + <td>Passing data using <a href="/en-US/docs/Web/Guide/API/DOM/The_structured_clone_algorithm">structured cloning</a></td> + <td>13</td> + <td>{{CompatGeckoDesktop(8)}}</td> + <td>10.0</td> + <td>11.5</td> + <td>6</td> + </tr> + <tr> + <td>Passing data using <a class="external" href="http://www.w3.org/html/wg/drafts/html/master/infrastructure.html#transferable-objects">transferable objects</a></td> + <td>17 {{property_prefix("webkit")}}<br> + 21</td> + <td>{{CompatGeckoDesktop(18)}}</td> + <td>{{CompatNo}}</td> + <td>15</td> + <td>6</td> + </tr> + <tr> + <td>Global {{domxref("window.URL", "URL")}}</td> + <td>10<sup>[3]</sup><br> + 23</td> + <td>{{CompatGeckoDesktop(21)}}</td> + <td>11</td> + <td>15</td> + <td>6<sup>[3]</sup></td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome Mobile</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>4.4</td> + <td>4<sup>[1]</sup></td> + <td>3.5</td> + <td>1.0.1</td> + <td>10.0</td> + <td>11.5<sup>[1]</sup></td> + <td>5.1<sup>[2]</sup></td> + </tr> + <tr> + <td>Shared workers</td> + <td>{{CompatNo}}</td> + <td>4<sup>[1]</sup></td> + <td>8</td> + <td>1.0.1</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>Passing data using <a href="/en-US/docs/Web/Guide/API/DOM/The_structured_clone_algorithm">structured cloning</a></td> + <td>{{CompatNo}}</td> + <td>4</td> + <td>8</td> + <td>1.0.1</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>Passing data using <a class="external" href="http://www.w3.org/html/wg/drafts/html/master/infrastructure.html#transferable-objects">transferable objects</a></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>18</td> + <td>1.0.1</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Chrome 和 Opera 會丟出錯誤："<code>Uncaught SecurityError: Failed to construct 'Worker': Script at 'file:///Path/to/worker.js' cannot be accessed from origin 'null'.</code>"，當從 local 端而非網域執行 worker。</p> + +<p>[2] Safari 7.1.2 可以從 worker 呼叫 <code>console.log，但並不會任何效果，而更早的版本則是不允許呼叫</code> <code>console.log。</code></p> + +<p>[3] 會有前綴 <code>webkitURL</code>.</p> + +<h2 id="延伸閱讀">延伸閱讀</h2> + +<ul> + <li><code><a class="internal" href="/en-US/docs/Web/API/Worker">Worker</a></code> interface</li> + <li><code><a class="internal" href="/en-US/docs/Web/API/SharedWorker">SharedWorker</a></code> interface</li> + <li><a href="/en-US/docs/Web/API/Worker/Functions_and_classes_available_to_workers">Functions available to workers</a></li> + <li><a href="/en-US/docs/Web/API/Web_Workers_API/Using_web_workers">Advanced concepts and examples</a></li> +</ul> diff --git a/files/zh-tw/web/api/webgl_api/index.html b/files/zh-tw/web/api/webgl_api/index.html new file mode 100644 index 0000000000..561594474c --- /dev/null +++ b/files/zh-tw/web/api/webgl_api/index.html @@ -0,0 +1,255 @@ +--- +title: WebGL +slug: Web/API/WebGL_API +tags: + - WebGL +translation_of: Web/API/WebGL_API +--- +<p>{{WebGLSidebar}}</p> + +<p class="summary">WebGL (Web Graphics Library) 是一個透過瀏覽器渲染3D及2D圖像的 JavaScript API ，且不需要安裝任何插件。 WebGL 透過與OpenGL ES 2.0緊密連結的API，將3D圖像帶入HTML5中，並可透過canvas元素呈現於瀏覽器中</p> + +<p>Support for WebGL is present in <a href="/en-US/Firefox" title="Firefox 4 for developers">Firefox</a> 4+, <a href="http://www.google.com/chrome/" title="http://www.google.com/chrome/">Google Chrome</a> 9+, <a href="http://www.opera.com/" title="http://www.opera.com/">Opera</a> 12+, <a href="http://www.apple.com/safari/" title="http://www.apple.com/fr/safari/">Safari </a>5.1+ 以及 <a href="http://windows.microsoft.com/en-us/internet-explorer/browser-ie" title="http://windows.microsoft.com/en-us/internet-explorer/download-ie">Internet Explorer</a> 11+; 然而，使用者的 GPU 也必須支援。</p> + +<div class="cleared row topicpage-table"> +<div class="section"> +<h2 class="Documentation" id="Development_topics">Development topics</h2> + +<dl> + <dt><a href="/zh-TW/docs/Web/API/WebGL_API/Tutorial/Getting_started_with_WebGL" title="WebGL/Getting started with WebGL">從 WebGL 開始吧</a></dt> + <dd>如何設立一個 WebGL 環境。</dd> + <dt><a href="/zh-TW/docs/Web/API/WebGL_API/Tutorial/Adding_2D_content_to_a_WebGL_context" title="WebGL/Adding 2D content to a WebGL context">增加 2D 的東西到 WebGL 環境</a></dt> + <dd>如何使用 WebGL 來呈現一個簡單的平面形狀。</dd> + <dt><a href="/en-US/docs/WebGL/Using_shaders_to_apply_color_in_WebGL" title="WebGL/Using shaders to apply color in WebGL">Using shaders to apply color in WebGL</a></dt> + <dd>Demonstrates how to add color to shapes using shaders.</dd> + <dt><a href="/en-US/docs/WebGL/Animating_objects_with_WebGL" title="WebGL/Animating objects with WebGL">Animating objects with WebGL</a></dt> + <dd>Shows how to rotate and translate objects to create simple animations.</dd> + <dt><a href="/en-US/docs/WebGL/Creating_3D_objects_using_WebGL" title="WebGL/Creating 3D objects using WebGL">Creating 3D objects using WebGL</a></dt> + <dd>Shows how to create and animate a 3D object (in this case, a cube).</dd> + <dt><a href="/en-US/docs/WebGL/Using_textures_in_WebGL" title="WebGL/Using textures in WebGL">Using textures in WebGL</a></dt> + <dd>Demonstrates how to map textures onto the faces of an object.</dd> + <dt><a href="/en-US/docs/WebGL/Lighting_in_WebGL" title="WebGL/Lighting in WebGL">Lighting in WebGL</a></dt> + <dd>How to simulate lighting effects in your WebGL context.</dd> + <dt><a href="/en-US/docs/WebGL/Animating_textures_in_WebGL" title="WebGL/Animating textures in WebGL">Animating textures in WebGL</a></dt> + <dd>Shows how to animate textures; in this case, by mapping an Ogg video onto the faces of a rotating cube.</dd> + <dt><a href="/en-US/docs/WebGL/WebGL_best_practices" title="WebGL/WebGL best practices">WebGL best practices</a></dt> + <dd>Tips and suggestions to improve your WebGL content.</dd> + <dt><a href="/en-US/docs/WebGL/Cross-Domain_Textures" title="WebGL/Cross-Domain Textures">Cross-domain textures</a></dt> + <dd>Information about loading textures from domains other than the one from which your content was loaded.</dd> + <dt><a href="/en-US/docs/WebGL/Using_Extensions" title="WebGL/Using_Extensions">Using extensions</a></dt> + <dd>How to use extensions that are available in WebGL.</dd> +</dl> +</div> + +<div class="section"> +<h2 class="Related_Topics" id="資源">資源</h2> + +<dl> + <dt><a class="link-https" href="https://www.khronos.org/registry/webgl/specs/1.0/" title="https://www.khronos.org/registry/webgl/specs/1.0/">WebGL Specification</a></dt> + <dd>The WebGL specification.</dd> + <dt><a href="http://www.khronos.org/webgl/" title="http://www.khronos.org/webgl/">Khronos WebGL site</a></dt> + <dd>The main web site for WebGL at the Khronos Group.</dd> + <dt><a href="http://learningwebgl.com/blog/?page_id=1217" title="http://learningwebgl.com/blog/">Learning WebGL</a></dt> + <dd>A site with tutorials on how to use WebGL.</dd> + <dt><a href="http://www.html5rocks.com/en/tutorials/webgl/webgl_fundamentals/" title="http://www.html5rocks.com/en/tutorials/webgl/webgl_fundamentals/">WebGL Fundamentals</a></dt> + <dd>A basic tutorial with fundamentals of WebGL.</dd> + <dt><a href="http://games.greggman.com/game/webgl-2d-matrices/">WebGL Matrices</a></dt> + <dd>An introduction to matrices' use in 2D WebGL. This series also goes on to explain the math behind perspective 3D.</dd> + <dt><a href="http://learningwebgl.com/cookbook/index.php/" title="http://learningwebgl.com/cookbook/index.php/">The WebGL Cookbook</a></dt> + <dd>A web site with handy recipes for writing WebGL code.</dd> + <dt><a href="http://planet-webgl.org/" title="http://planet-webgl.org/">Planet WebGL</a></dt> + <dd>A feed aggregator for people involved in the WebGL community.</dd> + <dt><a href="http://code.google.com/p/ewgl-matrices/" title="http://code.google.com/p/ewgl-matrices/">ewgl-matrices</a></dt> + <dd>A blazing fast matrix library for WebGL</dd> + <dt><a class="link-https" href="https://github.com/toji/gl-matrix" title="https://github.com/toji/gl-matrix">glMatrix</a></dt> + <dd>JavaScript Matrix and Vector library for High Performance WebGL apps</dd> + <dt><a href="http://code.google.com/p/webgl-mjs/" title="http://code.google.com/p/webgl-mjs/">mjs</a></dt> + <dd><span>A JavaScript vector and matrix math library, optimized for WebGL usage.</span></dd> + <dt><a href="http://sylvester.jcoglan.com/" title="http://sylvester.jcoglan.com/">Sylvester</a></dt> + <dd>An open source library for manipulating vectors and matrices. Not optimized for WebGL but extremely robust.</dd> + <dt><a href="http://webglplayground.net" title="http://webglplayground.net">WebGL playground</a></dt> + <dd>An online tool for creating and sharing WebGL projects. Good for quick prototyping and experimenting.</dd> + <dt><a href="http://www.webglacademy.com" title="http://www.webglacademy.com">WebGL Academy</a></dt> + <dd>An HTML/Javascript editor with tutorials to learn basics of webgl programming.</dd> + <dt> </dt> +</dl> +</div> +</div> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<div>{{CompatibilityTable}}</div> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Firefox (Gecko)</th> + <th>Chrome</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>基本支援</td> + <td>{{CompatGeckoDesktop("2.0")}}</td> + <td>9</td> + <td>11</td> + <td>12 (experiment)</td> + <td>5.1 (experiment)</td> + </tr> + <tr> + <td><a href="http://www.khronos.org/registry/gles/extensions/OES/OES_texture_float.txt" title="http://www.khronos.org/registry/gles/extensions/OES/OES_texture_float.txt"><code>OES_texture_float</code></a></td> + <td>{{CompatGeckoDesktop("6.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><a href="http://www.khronos.org/registry/webgl/extensions/OES_standard_derivatives/" title="http://www.khronos.org/registry/webgl/extensions/OES_standard_derivatives/"><code>OES_standard_derivatives</code></a></td> + <td>{{CompatGeckoDesktop("10.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><a href="/en-US/docs/WebGL/Using_Extensions#EXT_texture_filter_anisotropic" title="WebGL/Using_Extensions#EXT_texture_filter_anisotropic"><code>EXT_texture_filter_anisotropic</code></a></td> + <td>{{CompatGeckoDesktop("13.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><a href="/en-US/docs/WebGL/Using_Extensions#WEBGL_compressed_texture_s3tc" title="WebGL/Using_Extensions#WEBGL_compressed_texture_s3tc"><code>WEBGL_compressed_texture_s3tc</code></a></td> + <td>{{CompatGeckoDesktop("15.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>drawingBufferWidth</code> and <code>drawingBufferHeight</code> attributes</td> + <td>{{CompatGeckoDesktop("9.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Firefox Mobile (Gecko)</th> + <th>Chrome for Android</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>4</td> + <td>25 (experiment)</td> + <td>{{CompatNo}}</td> + <td>12 (experiment)</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>drawingBufferWidth</code> and <code>drawingBufferHeight</code> attributes</td> + <td>{{CompatGeckoMobile("9.0")}}</td> + <td>25</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><a href="http://www.khronos.org/registry/gles/extensions/OES/OES_texture_float.txt" title="http://www.khronos.org/registry/gles/extensions/OES/OES_texture_float.txt"><code>OES_texture_float</code></a></td> + <td>{{CompatGeckoMobile("6.0")}}</td> + <td>25</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><a href="http://www.khronos.org/registry/webgl/extensions/OES_standard_derivatives/" title="http://www.khronos.org/registry/webgl/extensions/OES_standard_derivatives/"><code>OES_standard_derivatives</code></a></td> + <td>{{CompatGeckoMobile("10.0")}}</td> + <td>25</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><a href="/en-US/docs/WebGL/Using_Extensions#EXT_texture_filter_anisotropic" title="WebGL/Using_Extensions#EXT_texture_filter_anisotropic"><code>EXT_texture_filter_anisotropic</code></a></td> + <td>{{CompatGeckoMobile("13.0")}}</td> + <td>25</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>OES_element_index_uint</code></td> + <td>{{CompatUnknown}}</td> + <td>25</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>OES_vertex_array_object</code></td> + <td>{{CompatUnknown}}</td> + <td>25</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><a href="/en-US/docs/WebGL/Using_Extensions#WEBGL_compressed_texture_s3tc" title="WebGL/Using_Extensions#WEBGL_compressed_texture_s3tc"><code>WEBGL_compressed_texture_s3tc</code></a></td> + <td>{{CompatGeckoMobile("15.0")}}</td> + <td>25<br> + prefixed with <span style="color: #222222; font-family: courier new,monospace; font-size: 12.66px; line-height: normal; white-space: pre-wrap;">WEBKIT_</span></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>WEBKIT_EXT_texture_filter_nisotropic</code></td> + <td>{{CompatNo}}</td> + <td>25</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h3 id="相容性小記">相容性小記</h3> + +<p>In addition to the browser, the GPU itself also needs to support the feature. So, for example, S3 Texture Compression (S3TC) is only available on Tegra-based tablets. Most browsers make the WebGL context available through the <code>webgl</code> context name, but older ones need <code>experimental-webgl</code> as well. In addition, the upcoming WebGL 2 is fully backwards-compatible and will have the context name <code>experimental-webgl2</code> in the future for testing.</p> + +<h3 id="Gecko_小記">Gecko 小記</h3> + +<h4 id="WebGL_debugging_and_testing">WebGL debugging and testing</h4> + +<p>Starting with Gecko 10.0 {{geckoRelease("10.0")}}, there are two preferences available which let you control the capabilities of WebGL for testing purposes:</p> + +<dl> + <dt><code>webgl.min_capability_mode</code></dt> + <dd>A Boolean property that, when <code>true</code>, enables a minimum capability mode. When in this mode, WebGL is configured to only support the bare minimum feature set and capabilities required by the WebGL specification. This lets you ensure that your WebGL code will work on any device or browser, regardless of their capabilities. This is <code>false</code> by default.</dd> + <dt><code>webgl.disable_extensions</code></dt> + <dd>A Boolean property that, when <code>true</code>, disables all WebGL extensions. This is <code>false</code> by default.</dd> +</dl> + +<h2 id="你也可以看看">你也可以看看</h2> + +<p>Raw WebGL: a talk by Nick Desaulniers:</p> + +<p>{{EmbedYouTube("H4c8t6myAWU")}}</p> diff --git a/files/zh-tw/web/api/webgl_api/tutorial/adding_2d_content_to_a_webgl_context/index.html b/files/zh-tw/web/api/webgl_api/tutorial/adding_2d_content_to_a_webgl_context/index.html new file mode 100644 index 0000000000..45de8b801f --- /dev/null +++ b/files/zh-tw/web/api/webgl_api/tutorial/adding_2d_content_to_a_webgl_context/index.html @@ -0,0 +1,280 @@ +--- +title: 增加一個 2D 物件到 WebGL 環境 +slug: Web/API/WebGL_API/Tutorial/Adding_2D_content_to_a_WebGL_context +translation_of: Web/API/WebGL_API/Tutorial/Adding_2D_content_to_a_WebGL_context +--- +<div>{{WebGLSidebar("Tutorial")}} {{PreviousNext("Web/API/WebGL_API/Tutorial/Getting_started_with_WebGL", "Web/API/WebGL_API/Tutorial/Using_shaders_to_apply_color_in_WebGL")}}</div> + +<p>當你<a href="/zh-TW/docs/Web/API/WebGL_API/Tutorial/Getting_started_with_WebGL">建立了WebGL的context</a>後，便可開始渲染。最簡單的例子就是加入一個普通的正方形。接下來，我們會介紹如何畫一個正方形。</p> + +<h2 id="畫場景">畫場景</h2> + +<p>首先我們需要知道雖然這個範例只是要畫一個正方形，但我們還是在3D的空間裡作圖。基本上，我們就是畫一個正方形並把它放在相機前面，使正方形與使用者的視角垂直。我們要定義一個 shader，透過它來渲染我們的物件。接下來，我們會展示如何在螢幕前顯示一個正方形。</p> + +<h3 id="Shader">Shader</h3> + +<p>WebGL Shader使用 <a href="https://www.khronos.org/files/opengles_shading_language.pdf">OpenGL ES Shading Language</a>。 這邊不討論 shader 的細節的，但簡而言之，我們需要定義兩個shader (GPU上可執行的函數): vertex shader 和 fragment shader。這兩個 shader 會以字串的形式傳入WebGL，編譯後在GPU上執行。</p> + +<h4 id="Vertex_shader">Vertex shader</h4> + +<p>Vertex shader是用來定義一個變數 gl_Position 的值來控制畫布空間的值(-1到+1)，下面的範例，我們設了一個變數<code>aVertexPosition</code>用來記錄 vertex 的位置。接下來我們將該位置乘上兩個4x4的矩陣(<code>uProjectionMatrix</code>和<code>uModelMatrix</code>)，並將結果設定為 gl_Position 的值。如果想要了解更多關於 Projection 和其他矩陣可以參閱這篇<a href="https://webglfundamentals.org/webgl/lessons/webgl-3d-perspective.html">文件</a>。</p> + +<pre class="brush: html"> // Vertex shader program + + const vsSource = ` + attribute vec4 aVertexPosition; + + uniform mat4 uModelViewMatrix; + uniform mat4 uProjectionMatrix; + + void main() { + gl_Position = uProjectionMatrix * uModelViewMatrix * aVertexPosition; + } + `; +</pre> + +<h4 id="Fragment_shader">Fragment shader</h4> + +<p>每次 vertex shader 給 gl_Position 1到3個值的時候，它會分別畫出點、線、三角形。畫圖的時候，會呼叫 fragment shader 來詢問每個 pixel 的顏色。在這個範例中，我們對於每次詢問都回傳白色。</p> + +<p><code>gl_FragColor</code> 是GL預設的變數用來定義每個 fragment 的顏色，透過設定該變數的值來定義每個 pixel 的顏色，如下：</p> + +<pre class="brush: html"> const fsSource = ` + void main() { + gl_FragColor = vec4(1.0, 1.0, 1.0, 1.0); + } + `; +</pre> + +<h3 id="初始化_shader">初始化 shader</h3> + +<p>現在我們已經定義了兩個 shader ，我們接下來要將它們傳入WebGL，編譯並連結。下面的程式碼呼叫了 loadShader 來建立兩個shader。接下來，我們要新增一個程式，並將 shader 加入該程式，並將程式連結起來。如果編譯或連接失敗，程式碼會顯示錯誤訊息。</p> + +<p> </p> + +<pre class="brush: js">// +// 初始化 shader 來告知WebGL怎麼畫 +// +function initShaderProgram(gl, vsSource, fsSource) { + const vertexShader = loadShader(gl, gl.VERTEX_SHADER, vsSource); + const fragmentShader = loadShader(gl, gl.FRAGMENT_SHADER, fsSource); + + // 建立 shader 程式 + + const shaderProgram = gl.createProgram(); + gl.attachShader(shaderProgram, vertexShader); + gl.attachShader(shaderProgram, fragmentShader); + gl.linkProgram(shaderProgram); + + // 錯誤處理 + + if (!gl.getProgramParameter(shaderProgram, gl.LINK_STATUS)) { + alert('Unable to initialize the shader program: ' + gl.getProgramInfoLog(shaderProgram)); + return null; + } + + return shaderProgram; +} + +// +// creates a shader of the given type, uploads the source and +// compiles it. +// +function loadShader(gl, type, source) { + const shader = gl.createShader(type); + + // Send the source to the shader object + + gl.shaderSource(shader, source); + + // Compile the shader program + + gl.compileShader(shader); + + // See if it compiled successfully + + if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) { + alert('An error occurred compiling the shaders: ' + gl.getShaderInfoLog(shader)); + gl.deleteShader(shader); + return null; + } + + return shader; +} +</pre> + +<p> </p> + +<p>我們可以透過呼叫 initShaderProgram 來建立 shader 程式</p> + +<pre class="brush: js"> const shaderProgram = initShaderProgram(gl, vsSource, fsSource); +</pre> + +<p>接下來我們需要找到 WebGL 生成出的位置。這個例子中我們有一個 attribute、兩個 uniform。 Attributes 從 buffer 獲得值。每次迭代時，vertex shader 從 buffer 得到下一個值並傳入到 attribute。 Uniform 則像是 Javascript 的全域變數。每次迭代，他們的值不會改變。為了之後方便，我們將 shader 程式與 attribute 和 uniform 存放在同一個物件中。</p> + +<pre class="brush: js"> const programInfo = { + program: shaderProgram, + attribLocations: { + vertexPosition: gl.getAttribLocation(shaderProgram, 'aVertexPosition'), + }, + uniformLocations: { + projectionMatrix: gl.getUniformLocation(shaderProgram, 'uProjectionMatrix'), + modelViewMatrix: gl.getUniformLocation(shaderProgram, 'uModelViewMatrix'), + }, + }; +</pre> + +<h2 id="建立正方形平面">建立正方形平面</h2> + +<p>在我們渲染前，我們要建立一個 buffer 用來儲存頂點的座標。在此我們宣告一個函數 <code>initBuffers()</code> ，隨著之後建立更多複雜的物件，這個動作會重複見到很多次。</p> + +<pre class="brush: js">function initBuffers(gl) { + + // 建立一個 buffer 來儲存正方形的座標 + + const positionBuffer = gl.createBuffer(); + + // Select the positionBuffer as the one to apply buffer + // operations to from here out. + + gl.bindBuffer(gl.ARRAY_BUFFER, positionBuffer); + + // Now create an array of positions for the square. + + const positions = [ + 1.0, 1.0, + -1.0, 1.0, + 1.0, -1.0, + -1.0, -1.0, + ]; + + // Now pass the list of positions into WebGL to build the + // shape. We do this by creating a Float32Array from the + // JavaScript array, then use it to fill the current buffer. + + gl.bufferData(gl.ARRAY_BUFFER, + new Float32Array(positions), + gl.STATIC_DRAW); + + return { + position: positionBuffer, + }; +} +</pre> + +<p>這個步驟非常簡單，一開始呼叫<code>gl</code>物件的函數 {{domxref("WebGLRenderingContext.createBuffer()", "createBuffer()")}} 來產生一個儲存座標的 buffer，並將將該 buffer 綁定 WebGL 的 context。</p> + +<p>完成後，我們宣告一個陣列來儲存正方形平面各頂點的座標，並轉型為浮點數陣列並用{{domxref("WebGLRenderingContext.bufferData()", "bufferData()")}}函數傳入 <code>gl</code> 物件。</p> + +<h2 id="渲染場景">渲染場景</h2> + +<p>Shader 建立好了、位置也確定好了、正方形平面頂點的位置也已經放到 buffer後，我們就可以實際來渲染場景了。因為這個例子沒有任何的動畫，<code>drawScene()</code>函數非常單純。</p> + +<pre class="brush: js">function drawScene(gl, programInfo, buffers) { + gl.clearColor(0.0, 0.0, 0.0, 1.0); // 設定為全黑 + gl.clearDepth(1.0); // 清除所有東西 + gl.enable(gl.DEPTH_TEST); // Enable 深度測試 + gl.depthFunc(gl.LEQUAL); // Near things obscure far things + + // 開始前先初始化畫布 + + gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); + + // Create a perspective matrix, a special matrix that is + // used to simulate the distortion of perspective in a camera. + // Our field of view is 45 degrees, with a width/height + // ratio that matches the display size of the canvas + // and we only want to see objects between 0.1 units + // and 100 units away from the camera. + + const fieldOfView = 45 * Math.PI / 180; // in radians + const aspect = gl.canvas.clientWidth / gl.canvas.clientHeight; + const zNear = 0.1; + const zFar = 100.0; + const projectionMatrix = mat4.create(); + + // note: glmatrix.js always has the first argument + // as the destination to receive the result. + mat4.perspective(projectionMatrix, + fieldOfView, + aspect, + zNear, + zFar); + + // Set the drawing position to the "identity" point, which is + // the center of the scene. + const modelViewMatrix = mat4.create(); + + // Now move the drawing position a bit to where we want to + // start drawing the square. + + mat4.translate(modelViewMatrix, // destination matrix + modelViewMatrix, // matrix to translate + [-0.0, 0.0, -6.0]); // amount to translate + + // Tell WebGL how to pull out the positions from the position + // buffer into the vertexPosition attribute. + { + const numComponents = 2; // pull out 2 values per iteration + const type = gl.FLOAT; // the data in the buffer is 32bit floats + const normalize = false; // don't normalize + const stride = 0; // how many bytes to get from one set of values to the next + // 0 = use type and numComponents above + const offset = 0; // how many bytes inside the buffer to start from + gl.bindBuffer(gl.ARRAY_BUFFER, buffers.position); + gl.vertexAttribPointer( + programInfo.attribLocations.vertexPosition, + numComponents, + type, + normalize, + stride, + offset); + gl.enableVertexAttribArray( + programInfo.attribLocations.vertexPosition); + } + + // Tell WebGL to use our program when drawing + + gl.useProgram(programInfo.program); + + // Set the shader uniforms + + gl.uniformMatrix4fv( + programInfo.uniformLocations.projectionMatrix, + false, + projectionMatrix); + gl.uniformMatrix4fv( + programInfo.uniformLocations.modelViewMatrix, + false, + modelViewMatrix); + + { + const offset = 0; + const vertexCount = 4; + gl.drawArrays(gl.TRIANGLE_STRIP, offset, vertexCount); + } +} + +</pre> + +<p>第一步，我們先將畫布背景設定為黑色，並設定相機的視角。我們將角度設為45°，並設定成與畫布的長寬比相同。另外我們指定我們只要渲染離相機 0.1 ~ 100 單位遠的物件。</p> + +<p>接下來，我們讀入正方形的位置，並把它擺在離相機6單位遠的位置。然後我們將正方形頂點的 buffer 綁定到 gl 上。最後我們呼叫{{domxref("WebGLRenderingContext.drawArrays()", "drawArrays()")}}函數來渲染物件。</p> + +<p>{{EmbedGHLiveSample('webgl-examples/tutorial/sample2/index.html', 670, 510) }}</p> + +<p><a href="https://github.com/mdn/webgl-examples/tree/gh-pages/tutorial/sample2">檢視完整程式碼</a> | <a href="http://mdn.github.io/webgl-examples/tutorial/sample2/">開啟新頁面來檢視結果</a></p> + +<h2 id="矩陣運算">矩陣運算</h2> + +<p>矩陣的運算看起來很複雜，但其實<a href="https://webglfundamentals.org/webgl/lessons/webgl-2d-matrices.html">一步一步運算其實不會那麼困難</a>。大部分使用者不會寫自己的運算函數，多半是使用現成的矩陣函數庫，這個例子中我們用的是 <a href="http://glmatrix.net/">glMatrix library</a> 。</p> + +<p>可參考以下資料</p> + +<ul> + <li><a href="https://webglfundamentals.org/webgl/lessons/webgl-2d-matrices.html">Matrices</a> on WebGLFundamentals</li> + <li><a class="external" href="http://mathworld.wolfram.com/Matrix.html">Matrices</a> on Wolfram MathWorld</li> + <li><a class="external" href="http://en.wikipedia.org/wiki/Matrix_(mathematics)">Matrix</a> on Wikipedia</li> +</ul> + +<p>{{PreviousNext("Web/API/WebGL_API/Tutorial/Getting_started_with_WebGL", "Web/API/WebGL_API/Tutorial/Using_shaders_to_apply_color_in_WebGL")}}</p> diff --git a/files/zh-tw/web/api/webgl_api/tutorial/animating_objects_with_webgl/index.html b/files/zh-tw/web/api/webgl_api/tutorial/animating_objects_with_webgl/index.html new file mode 100644 index 0000000000..cea74d65cf --- /dev/null +++ b/files/zh-tw/web/api/webgl_api/tutorial/animating_objects_with_webgl/index.html @@ -0,0 +1,55 @@ +--- +title: 利用 WebGL 產生動畫 +slug: Web/API/WebGL_API/Tutorial/Animating_objects_with_WebGL +translation_of: Web/API/WebGL_API/Tutorial/Animating_objects_with_WebGL +--- +<p>{{WebGLSidebar("Tutorial")}} {{PreviousNext("Web/API/WebGL_API/Tutorial/Using_shaders_to_apply_color_in_WebGL", "Web/API/WebGL_API/Tutorial/Creating_3D_objects_using_WebGL") }}</p> + +<p>這個章節中，我們將示範如何旋轉之前的正方形平面。</p> + +<h2 id="旋轉正方形">旋轉正方形</h2> + +<p>首先我們需要宣告一個變數來追蹤現在正方形旋轉的角度:</p> + +<pre class="brush: js">var squareRotation = 0.0; +</pre> + +<p>Now we need to update the <code>drawScene()</code> function to apply the current rotation to the square when drawing it. After translating to the initial drawing position for the square, we apply the rotation like this:</p> + +<pre class="brush: js"> mat4.rotate(modelViewMatrix, // destination matrix + modelViewMatrix, // matrix to rotate + squareRotation, // amount to rotate in radians + [0, 0, 1]); // axis to rotate around +</pre> + +<p>This rotates the modelViewMatrix by the current value of <code>squareRotation</code>, around the Z axis.</p> + +<p>To actually animate, we need to add code that changes the value of <code>squareRotation</code> over time. We can do that by creating a new variable to track the time at which we last animated (let's call it <code>then</code>), then adding the following code to the end of the main function</p> + +<pre class="brush: js"> var then = 0; + + // Draw the scene repeatedly + function render(now) { + now *= 0.001; // convert to seconds + const deltaTime = now - then; + then = now; + + drawScene(gl, programInfo, buffers, deltaTime); + + requestAnimationFrame(render); + } + requestAnimationFrame(render); +</pre> + +<p>This code uses <code>requestAnimationFrame</code> to ask the browser call the function "<code>render</code>" each frame. <code>requestAnimationFrame</code> passes us the time in milliseconds since the page loaded. We convert that to seconds and then subtract it from the last time to compute <code>deltaTime</code> which is the number of second since the last frame was rendered. At the end of drawscene we add the code to update <code>squareRotation.</code></p> + +<pre class="brush: js"><code> squareRotation += deltaTime;</code> +</pre> + +<p>This code uses the amount of time that's passed since the last time we updated the value of <code>squareRotation</code> to determine how far to rotate the square.</p> + +<p>{{EmbedGHLiveSample('webgl-examples/tutorial/sample4/index.html', 670, 510) }}</p> + +<p><a href="https://github.com/mdn/webgl-examples/tree/gh-pages/tutorial/sample4">View the complete code</a> | <a href="http://mdn.github.io/webgl-examples/tutorial/sample4/">Open this demo on a new page</a></p> + +<p>{{PreviousNext("Web/API/WebGL_API/Tutorial/Using_shaders_to_apply_color_in_WebGL", "Web/API/WebGL_API/Tutorial/Creating_3D_objects_using_WebGL") }}</p> diff --git a/files/zh-tw/web/api/webgl_api/tutorial/getting_started_with_webgl/index.html b/files/zh-tw/web/api/webgl_api/tutorial/getting_started_with_webgl/index.html new file mode 100644 index 0000000000..ef5e910f93 --- /dev/null +++ b/files/zh-tw/web/api/webgl_api/tutorial/getting_started_with_webgl/index.html @@ -0,0 +1,73 @@ +--- +title: WebGL 入門 +slug: Web/API/WebGL_API/Tutorial/Getting_started_with_WebGL +tags: + - WebGL + - 教學 +translation_of: Web/API/WebGL_API/Tutorial/Getting_started_with_WebGL +--- +<p>{{WebGLSidebar("Tutorial")}} {{Next("Web/API/WebGL_API/Tutorial/Adding_2D_content_to_a_WebGL_context")}}</p> + +<p><a href="http://www.khronos.org/webgl/" title="http://www.khronos.org/webgl/">WebGL</a> 讓網頁內容能藉由一種基於 <a href="http://www.khronos.org/opengles/" title="http://www.khronos.org/opengles/">OpenGL ES</a> 2.0 的 API 的幫助，於支援此 API 的瀏覽器環境中，不需使用外掛程式就能在HTML的 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API"><code>canvas</code></a> 元素中實現二維及三維渲染。 WebGL 程式包含了由 JavaSrcipt 及著色器(GLSL)撰寫的控制碼以及在電腦的圖形處理器( GPU )上執行的特效程式碼(著色器程式碼)。WebGL 元素可以加入其他 HTML 元素之中並與網頁或網頁背景的其他部分混合。</p> + +<p>這篇文章將會向您介紹 WebGL 的基礎。這篇文章假設您已經對於三維圖學涉及的數學有所了解，並且它將不會被佯裝為三維圖學的教材。在我們的學習區域內有初學者指南讓你完成編程任務：<a href="https://developer.mozilla.org/zh-TW/docs/Learn/WebGL">Learn WebGL for 2D and 3D graphics</a>.</p> + +<p>在此教學文件中的程式碼範例都能在 <a href="https://github.com/mdn/webgl-examples/tree/gh-pages/tutorial">webgl-examples GitHub repository</a> 之中找到。</p> + +<h2 id="準備三維渲染">準備三維渲染</h2> + +<p>首先你需要一個 canvas 元素讓WebGL進行渲染。下面的 HTML 定義的 canvas 元素供後續的範例繪製。</p> + +<pre class="brush: html"><body> + <canvas id="glCanvas" width="640" height="480"></canvas> +</body></pre> + +<h3 id="準備_WebGL背景資料">準備 WebGL背景資料</h3> + +<div class="note"> +<p>背景資料為Context翻譯而來</p> +</div> + +<p>在下面的JavaScript 程式碼，當指令完成讀取後會執行 <code>main()</code> 函式。目的是為了設定 WebGL 背景資料並且開始渲染內容。</p> + +<pre class="brush: js">main(); + +// 從這開始 +function main() { + const canvas = document.querySelector("#glCanvas"); + // 初始化 GL context + const gl = canvas.getContext("webgl"); + + // 當 WebGL 有效才繼續執行 + if (gl === null) { + alert("無法初始化 WebGL，您的瀏覽器不支援。"); + return; + } + + // 設定清除色彩為黑色，完全不透明 + gl.clearColor(0.0, 0.0, 0.0, 1.0); + // 透過清除色來清除色彩緩衝區 + gl.clear(gl.COLOR_BUFFER_BIT); +}</pre> + +<p>在此我們做的第一件事是取得 canvas 元素的參考，並存入 canvas 變數中。</p> + +<p>一旦我們取得了 canvas ，我們透過呼叫 <a href="https://developer.mozilla.org/zh-TW/docs/Web/API/HTMLCanvasElement/getContext">getContext</a> 並傳入 <code>"webgl"</code> 字串來取得 <a href="https://developer.mozilla.org/zh-TW/docs/Web/API/WebGLRenderingContext">WebGLRenderingContext</a>。若瀏覽器不支援 webgl <code>getContext</code> 會回傳 <code>null</code> 同時會顯示訊息給使用者並且離開。</p> + +<p>如果成功初始化， <code>gl</code> 就會成為一個 WebGL背景資料的參考。在這裡我們設置清除色為黑色，並透過該色清除 context (用背景色重新繪製 canvas )。</p> + +<p>至此，您已經有足夠初始化 WebGL 背景資料的程式碼，並且準備好了等待接收內容的容器。</p> + +<p>{{EmbedGHLiveSample('webgl-examples/tutorial/sample1/index.html', 670, 510) }}</p> + +<p><a href="https://github.com/mdn/webgl-examples/tree/gh-pages/tutorial/sample1">檢視完整程式碼</a> | <a href="http://mdn.github.io/webgl-examples/tutorial/sample1/">開啟新頁面來檢視結果</a></p> + +<h2 id="亦可參考">亦可參考</h2> + +<ul> + <li><a href="https://dev.opera.com/articles/introduction-to-webgl-part-1/">An introduction to WebGL</a>: 由 Luz Caballero 撰寫，並出版在 dev.opera.com。 這篇文章點出了 WebGL 的意義，解釋了其運作(包含渲染管路的觀念)，並介紹了一些 WebGL libraries。</li> + <li><a href="http://webglfundamentals.org/">WebGL Fundamentals</a></li> + <li><a href="http://duriansoftware.com/joe/An-intro-to-modern-OpenGL.-Table-of-Contents.html">An intro to modern OpenGL:</a> 由 Joe Groff 撰寫的一系列關於 OpenGL 的好文章，提供了 OpenGL清楚的簡介，從其歷史到重要的圖像管路概念，以及一些展示其原理的範例。如果您完全不懂OpenGL，這將是一個好的入門介紹。</li> +</ul> + +<p>{{Next("Web/API/WebGL_API/Tutorial/Adding_2D_content_to_a_WebGL_context")}}</p> diff --git a/files/zh-tw/web/api/webgl_api/tutorial/index.html b/files/zh-tw/web/api/webgl_api/tutorial/index.html new file mode 100644 index 0000000000..549c3f40ba --- /dev/null +++ b/files/zh-tw/web/api/webgl_api/tutorial/index.html @@ -0,0 +1,41 @@ +--- +title: WebGL tutorial +slug: Web/API/WebGL_API/Tutorial +tags: + - TopicStub + - Tutorial + - WebGL +translation_of: Web/API/WebGL_API/Tutorial +--- +<div>{{WebGLSidebar}}</div> + +<div class="summary"> +<p><a class="external" href="http://www.khronos.org/webgl/" title="http://www.khronos.org/webgl/">WebGL</a> 讓網頁內容可以使用一個基於 <a class="external" href="http://www.khronos.org/opengles/" title="http://www.khronos.org/opengles/">OpenGL ES</a> 2.0 的API以在HTML {{HTMLElement("canvas")}}中執行3D渲染，且瀏覽器無需使用任何plug-in。WebGL programs 由JavaScript撰寫的指令碼以及透過電腦的Graphics Processing Unit (GPU)上運行的特殊效果程式碼(shader code)組成。WebGL元件可與其他HTML元件混合，並與該頁的其他部分或該頁背景組合使用。 </p> +</div> + +<p><span class="seoSummary">本教學描述如何使用 <code><canvas></code> 元件描繪 WebGL 圖像/圖形, 從基礎開始。提供的範例將讓你對於可以用WebGL做到什麼有清楚的概念，並提供程式碼片段讓你可以著手建立自己的內容。</span></p> + +<h2 id="開始之前">開始之前</h2> + +<p>使用<code><canvas></code> 元件不會非常困難，但你需要有對<a href="/en-US/docs/Web/HTML" title="HTML">HTML</a> 與 <a href="/en-US/docs/Web/JavaScript" title="JavaScript">JavaScript</a> 的基礎認識。<code><canvas></code> 元件跟WebGL在某些舊瀏覽器中不支援，但近來的每個主流瀏覽器都有支援。我們用 JavaScript context object 在canvas繪製圖形，這樣圖形就能動態(on the fly)產生。</p> + +<h2 id="教學文件">教學文件</h2> + +<dl> + <dt><a href="/Web/API/WebGL_API/Tutorial/Getting_started_with_WebGL">WebGL新手上路</a></dt> + <dd>如何建置 WebGL 環境</dd> + <dt><a href="/Web/API/WebGL_API/Tutorial/Adding_2D_content_to_a_WebGL_context">加入2D內容至WebGL環境</a></dt> + <dd>如何用 WebGL 渲染簡單平面的形狀</dd> + <dt><a href="/zh-TW/docs/Web/API/WebGL_API/Tutorial/Using_shaders_to_apply_color_in_WebGL">使用 shaders 在 WebGL 上色</a></dt> + <dd>示範如何使用 shaders 在圖形上上色</dd> + <dt><a href="/zh-TW/docs/Web/API/WebGL_API/Tutorial/Animating_objects_with_WebGL">WebGL 產生動畫</a></dt> + <dd>示範如何旋轉與移動物件以製作簡單的動畫</dd> + <dt><a href="/en-US/docs/Web/API/WebGL_API/Tutorial/Creating_3D_objects_using_WebGL">建立三維物件</a></dt> + <dd>示範如何創造並讓 3D 物件(立方體)有動畫</dd> + <dt><a href="/en-US/docs/Web/API/WebGL_API/Tutorial/Using_textures_in_WebGL">在物件表面貼上材質</a></dt> + <dd>示範如何在物件的表面上貼上材質圖</dd> + <dt><a href="/en-US/docs/Web/API/WebGL_API/Tutorial/Lighting_in_WebGL">模擬打光</a></dt> + <dd>如何在 WebGL 環境模擬打光效果</dd> + <dt><a href="/en-US/docs/Web/API/WebGL_API/Tutorial/Animating_textures_in_WebGL">讓材質產生動畫</a></dt> + <dd>如何移動材質圖，在範例中是將 Ogg 影片 貼到一個旋轉中的立方體</dd> +</dl> diff --git a/files/zh-tw/web/api/webgl_api/tutorial/using_shaders_to_apply_color_in_webgl/index.html b/files/zh-tw/web/api/webgl_api/tutorial/using_shaders_to_apply_color_in_webgl/index.html new file mode 100644 index 0000000000..b234bd013e --- /dev/null +++ b/files/zh-tw/web/api/webgl_api/tutorial/using_shaders_to_apply_color_in_webgl/index.html @@ -0,0 +1,123 @@ +--- +title: 使用 shaders 在 WebGL 上色 +slug: Web/API/WebGL_API/Tutorial/Using_shaders_to_apply_color_in_WebGL +translation_of: Web/API/WebGL_API/Tutorial/Using_shaders_to_apply_color_in_WebGL +--- +<p>{{WebGLSidebar("Tutorial")}} {{PreviousNext("Web/API/WebGL_API/Tutorial/Adding_2D_content_to_a_WebGL_context", "Web/API/WebGL_API/Tutorial/Animating_objects_with_WebGL")}}</p> + +<p><a href="/zh-TW/docs/Web/API/WebGL_API/Tutorial/Adding_2D_content_to_a_WebGL_context">上一篇</a>我們建立了一個正方形平面，接下來我們要透過修改 shakder 來加入顏色。</p> + +<h2 id="指定頂點顏色">指定頂點顏色</h2> + +<p>WebGL中物件是由許多頂點來組成，每個頂點有自己的座標、顏色。其他像素的屬性(顏色、位置)預設是透過計算多頂點的內差值來得到的。之前的例子，vertex shader 並沒有指定頂點任何顏色。</p> + +<p>In WebGL, objects are built using sets of vertices, each of which has a position and a color; by default, all other pixels' colors (and all its other attributes, including position) are computed using interpolation, automatically creating smooth gradients. Previously, our vertex shader didn't apply any specific colors to the vertices; between this and the fragment shader assigning the fixed color of white to each pixel, the entire square was rendered as solid white.</p> + +<p>Let's say we want to render a gradient in which each corner of the square is a different color: red, blue, green, and white. The first thing to do is to establish these colors for the four vertices. To do this, we first need to create an array of vertex colors, then store it into a WebGL buffer; we'll do that by adding the following code to our <code>initBuffers()</code> function:</p> + +<pre class="brush: js"> const colors = [ + 1.0, 1.0, 1.0, 1.0, // white + 1.0, 0.0, 0.0, 1.0, // red + 0.0, 1.0, 0.0, 1.0, // green + 0.0, 0.0, 1.0, 1.0, // blue + ]; + + const colorBuffer = gl.createBuffer(); + gl.bindBuffer(gl.ARRAY_BUFFER, colorBuffer); + gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(colors), gl.STATIC_DRAW); + + return { + position: positionBuffer, + color: colorBuffer, + }; +} +</pre> + +<p>這段程式碼一開始先宣告一個陣列來存放四個四維向量，分別為四個頂點的顏色。接下來，將陣列轉型為浮點數並存入一個新的 WebGL buffer 。</p> + +<p>為了使用這些顏色，我們需要修改 vertex shader，讓他可以從 buffer 中取得正確的顏色。</p> + +<pre class="brush: html"> const vsSource = ` + attribute vec4 aVertexPosition; + attribute vec4 aVertexColor; + + uniform mat4 uModelViewMatrix; + uniform mat4 uProjectionMatrix; + + varying lowp vec4 vColor; + + void main(void) { + gl_Position = uProjectionMatrix * uModelViewMatrix * aVertexPosition; + vColor = aVertexColor; + } + `; +</pre> + +<p>The key difference here is that for each vertex, we pass its color using a <code>varying</code> to the fragment shader.</p> + +<h2 id="替_fragment_上色">替 fragment 上色</h2> + +<p>我們重新回顧一下，<a href="/zh-TW/docs/Web/API/WebGL_API/Tutorial/Adding_2D_content_to_a_WebGL_context">之前</a>我們的 fragment shader 如下：</p> + +<pre class="brush: html"> const fsSource = ` + void main() { + gl_FragColor = vec4(1.0, 1.0, 1.0, 1.0); + } + `; +</pre> + +<p>為了要讓每個 pixel 使用內插的顏色，我們讓 <code>gl_FragColor</code> 取得 vColor的值。</p> + +<pre class="brush: html"> const fsSource = ` + varying lowp vec4 vColor; + + void main(void) { + gl_FragColor = vColor; + } + `; +</pre> + +<p>這樣的改變可以使每個 fragment 得到利用相對位置內插法所產生顏色，而不是得到一個固定的值。</p> + +<h2 id="畫出顏色">畫出顏色</h2> + +<p>接下來我們要</p> + +<p>Next, it's necessary to add the code look up the attribute location for the colors and setup that attribute for the shader program:</p> + +<pre class="brush: js"> const programInfo = { + program: shaderProgram, + attribLocations: { + vertexPosition: gl.getAttribLocation(shaderProgram, 'aVertexPosition'), + vertexColor: gl.getAttribLocation(shaderProgram, 'aVertexColor'), + }, + ...</pre> + +<p>Then, drawScene() can be revised to actually use these colors when drawing the square:</p> + +<pre class="brush: js"> // Tell WebGL how to pull out the colors from the color buffer + // into the vertexColor attribute. + { + const numComponents = 4; + const type = gl.FLOAT; + const normalize = false; + const stride = 0; + const offset = 0; + gl.bindBuffer(gl.ARRAY_BUFFER, buffers.color); + gl.vertexAttribPointer( + programInfo.attribLocations.vertexColor, + numComponents, + type, + normalize, + stride, + offset); + gl.enableVertexAttribArray( + programInfo.attribLocations.vertexColor); + } +</pre> + +<p>{{EmbedGHLiveSample('webgl-examples/tutorial/sample3/index.html', 670, 510) }}</p> + +<p><a href="https://github.com/mdn/webgl-examples/tree/gh-pages/tutorial/sample3">View the complete code</a> | <a href="http://mdn.github.io/webgl-examples/tutorial/sample3/">Open this demo on a new page</a></p> + +<p>{{PreviousNext("Web/API/WebGL_API/Tutorial/Adding_2D_content_to_a_WebGL_context", "Web/API/WebGL_API/Tutorial/Animating_objects_with_WebGL")}}</p> diff --git a/files/zh-tw/web/api/webrtc_api/index.html b/files/zh-tw/web/api/webrtc_api/index.html new file mode 100644 index 0000000000..1731f23739 --- /dev/null +++ b/files/zh-tw/web/api/webrtc_api/index.html @@ -0,0 +1,193 @@ +--- +title: WebRTC API +slug: Web/API/WebRTC_API +translation_of: Web/API/WebRTC_API +--- +<div>{{APIRef("WebRTC")}}</div> + +<p><span class="seoSummary"><strong>WebRTC</strong>（網路即時通訊技術）是一個提供 Web 應用程式及網站進行錄影或隨選播放串流音訊與影像的技術，可以直接使用瀏覽器進行資料交換而無須透過中介服務。</span>作為一個標準規格，WebRTC 可以提供任何瀏覽器在不需要安裝外掛程式或第三方軟體下，分享應用程式的資料和進行電話會議。</p> + +<p>WebRTC 由數個相關而互相協作的API以及網路協定組成。</p> + +<p>這裡的技術文件會幫助你了解 :</p> + +<p>WebRTC的基本構成，如何設置並同時使用其資料與媒體傳輸連線，以及更多有關資訊。</p> + +<h2 id="WebRTC_概念與使用">WebRTC 概念與使用</h2> + +<p>WebRTC 有許多服務目的，基本涵括了媒體獲取與串流API，他們為網頁提供了強大的多媒體功能，包括: 音視訊會議，檔案傳輸，身分識別管理，以及提供以傳輸{{Glossary("DTMF")}}訊號來與現存電話系統交互的介面。</p> + +<p>建立端點與端點間的連線完全不需要特定驅動程式抑或者第三方插件，在通常情況下也不需要任何中介伺服器</p> + +<p>WebRTC serves multiple purposes, and overlaps substantially with the Media Capture and Streams API. Together, they provide powerful multimedia capabilities to the Web, including support for audio and video conferencing, file exchange, identity management, and interfacing with legacy telephone systems by sending {{Glossary("DTMF")}} signals. Connections between peers can be made without requiring any special drivers or plug-ins, and can often be made without any intermediary servers.</p> + +<p>Connections between two peers are created using—and represented by—the {{domxref("RTCPeerConnection")}} interface. Once a connection has been established and opened, media streams ({{domxref("MediaStream")}}s) and/or data channels ({{domxref("RTCDataChannel")}}s) can be added to the connection.</p> + +<p>Media streams can consist of any number of tracks of media information; tracks, which are represented by objects based on the {{domxref("MediaStreamTrack")}} interface, may contain one of a number of types of media data, including audio, video, and text (such as subtitles or even chapter names). Most streams consist of at least one audio track and likely also a video track, and can be used to send and receive both live media or stored media information (such as a streamed movie).</p> + +<p>You can also use the connection between two peers to exchange arbitrary binary data using the {{domxref("RTCDataChannel")}} interface. This can be used for back-channel information, metadata exchange, game status packets, file transfers, or even as a primary channel for data transfer.</p> + +<p><em><strong>more details and links to relevant guides and tutorials needed</strong></em></p> + +<h2 id="WebRTC_interfaces">WebRTC interfaces</h2> + +<p>Because WebRTC provides interfaces that work together to accomplish a variety of tasks, we have divided up the interfaces in the list below by category. Please see the sidebar for an alphabetical list.</p> + +<h3 id="Connection_setup_and_management">Connection setup and management</h3> + +<p>These interfaces are used to set up, open, and manage WebRTC connections.</p> + +<dl> + <dt>{{domxref("RTCPeerConnection")}}</dt> + <dd>Represents a WebRTC connection between the local computer and a remote peer. It is used to handle efficient streaming of data between the two peers.</dd> + <dt>{{domxref("RTCDataChannel")}}</dt> + <dd>Represents a bi-directional data channel between two peers of a connection.</dd> + <dt>{{domxref("RTCDataChannelEvent")}}</dt> + <dd>Represents events that occur while attaching a {{domxref("RTCDataChannel")}} to a {{domxref("RTCPeerConnection")}}. The only event sent with this interface is {{event("datachannel")}}.</dd> + <dt>{{domxref("RTCSessionDescription")}}</dt> + <dd>Represents the parameters of a session. Each <code>RTCSessionDescription</code> consists of a description <a href="/en-US/docs/Web/API/RTCSessionDescription/type" title="The property RTCSessionDescription.type is an enum of type RTCSdpType describing the description's type."><code>type</code></a> indicating which part of the offer/answer negotiation process it describes and of the <a href="/en-US/docs/Glossary/SDP" title="SDP: SDP (Session Description Protocol) is the standard describing a peer-to-peer connection. SDP contains the codec, source address, and timing information of audio and video.">SDP</a> descriptor of the session.</dd> + <dt>{{domxref("RTCStatsReport")}}</dt> + <dd>Provides information detailing statistics for a connection or for an individual track on the connection; the report can be obtained by calling {{domxref("RTCPeerConnection.getStats()")}}.</dd> + <dt>{{domxref("RTCIceCandidate")}}</dt> + <dd>Represents a candidate internet connectivity establishment (ICE) server for establishing an {{domxref("RTCPeerConnection")}}.</dd> + <dt>{{domxref("RTCIceTransport")}}</dt> + <dd>Represents information about an internet connectivity establishment (ICE) transport.</dd> + <dt>{{domxref("RTCPeerConnectionIceEvent")}}</dt> + <dd>Represents events that occurs in relation to ICE candidates with the target, usually an {{domxref("RTCPeerConnection")}}. Only one event is of this type: {{event("icecandidate")}}.</dd> + <dt>{{domxref("RTCRtpSender")}}</dt> + <dd>Manages the encoding and transmission of data for a {{domxref("MediaStreamTrack")}} on an {{domxref("RTCPeerConnection")}}.</dd> + <dt>{{domxref("RTCRtpReceiver")}}</dt> + <dd>Manages the reception and decoding of data for a {{domxref("MediaStreamTrack")}} on an {{domxref("RTCPeerConnection")}}.</dd> + <dt>{{domxref("RTCTrackEvent")}}</dt> + <dd>Indicates that a new incoming {{domxref("MediaStreamTrack")}} was created and an associated {{domxref("RTCRtpReceiver")}} object was added to the {{domxref("RTCPeerConnection")}} object.</dd> +</dl> + +<h3 id="Identity_and_security">Identity and security</h3> + +<p>The WebRTC API includes a number of interfaces to manage security and identity.</p> + +<dl> + <dt>{{domxref("RTCIdentityProvider")}}</dt> + <dd>Enables a user agent is able to request that an identity assertion be generated or validated.</dd> + <dt>{{domxref("RTCIdentityAssertion")}}</dt> + <dd>Represents the identity of the a remote peer of the current connection. If no peer has yet been set and verified this interface returns <code>null</code>. Once set it can't be changed.</dd> + <dt>{{domxref("RTCIdentityProviderRegistrar")}}</dt> + <dd>Registers an identity provider (idP).</dd> + <dt>{{domxref("RTCIdentityEvent")}}</dt> + <dd>Represents an identity assertion generated by an identity provider (idP). This is usually for an {{domxref("RTCPeerConnection")}}. The only event sent with this type is {{event("identityresult")}}.</dd> + <dt>{{domxref("RTCIdentityErrorEvent")}}</dt> + <dd>Represents an error associated with the identity provider (idP). This is usually for an {{domxref("RTCPeerConnection")}}. Two events are sent with this type: {{event("idpassertionerror")}} and {{event("idpvalidationerror")}}.</dd> + <dt>{{domxref("RTCCertificate")}}</dt> + <dd>Represents a certificate that an {{domxref("RTCPeerConnection")}} uses to authenticate.</dd> +</dl> + +<h3 id="Telephony">Telephony</h3> + +<p>These interfaces are related to interactivity with public-switched telephone networks (PTSNs).</p> + +<dl> + <dt>{{domxref("RTCDTMFSender")}}</dt> + <dd>Manages the encoding and transmission of dual-tone multi-frequency (DTMF) signaling for an {{domxref("RTCPeerConnection")}}.</dd> + <dt>{{domxref("RTCDTMFToneChangeEvent")}}</dt> + <dd>Indicates an occurrence of a of dual-tone multi-frequency (DTMF). This event does not bubble (except where otherwise stated) and is not cancelable (except where otherwise stated).</dd> +</dl> + +<h2 id="Guides">Guides</h2> + +<dl> + <dt><a href="/en-US/docs/Web/API/WebRTC_API/Protocols">Introduction to WebRTC protocols</a></dt> + <dd>This article introduces the protocols on top of which the WebRTC API is built.</dd> + <dt><a href="/en-US/docs/Web/API/WebRTC_API/Connectivity">WebRTC connectivity</a></dt> + <dd>A guide to how WebRTC connections work and how the various protocols and interfaces can be used together to build powerful communication apps.</dd> + <dt><a href="/en-US/docs/Web/API/WebRTC_API/Session_lifetime">Lifetime of a WebRTC session</a></dt> + <dd>WebRTC lets you build peer-to-peer communication of arbitrary data, audio, or video—or any combination thereof—into a browser application. In this article, we'll look at the lifetime of a WebRTC session, from establishing the connection all the way through closing the connection when it's no longer needed.</dd> + <dt><a href="/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling">Signaling and two-way video calling</a></dt> + <dd>A tutorial and example which turbs a WebSocket-based chat system created for a previous example and adds support for opening video calls among participants. The chat server's WebSocket connection is used for WebRTC signaling.</dd> + <dt><a href="/en-US/docs/Web/API/WebRTC_API/Using_data_channels">Using WebRTC data channels</a></dt> + <dd>This guide covers how you can use a peer connection and an associated {{domxref("RTCDataChannel")}} to exchange arbitrary data between two peers.</dd> + <dt><a href="/en-US/docs/Web/API/WebRTC_API/Using_DTMF">Using DTMF with WebRTC</a></dt> + <dd>WebRTC's support for interacting with gateways that link to old-school telephone systems includes support for sending DTMF tones using the {{domxref("RTCDTMFSender")}} interface. This guide shows how to do so.</dd> +</dl> + +<h2 id="教學">教學</h2> + +<dl> + <dt><a href="/en-US/docs/Web/API/WebRTC_API/adapter.js">Improving compatibility using WebRTC adapter.js</a></dt> + <dd>The WebRTC organization <a href="https://github.com/webrtc/adapter/">provides on GitHub the WebRTC adapter</a> to work around compatibility issues in different browsers' WebRTC implementations. The adapter is a JavaScript shim which lets your code to be written to the specification so that it will "just work" in all browsers with WebRTC support.</dd> + <dt><a href="/en-US/docs/Web/API/WebRTC_API/Taking_still_photos">Taking still photos with WebRTC</a></dt> + <dd>This article shows how to use WebRTC to access the camera on a computer or mobile phone with WebRTC support and take a photo with it.</dd> + <dt><a href="/en-US/docs/Web/API/WebRTC_API/Simple_RTCDataChannel_sample">一個簡單的 RTCDataChannel 範例</a></dt> + <dd>{{domxref("RTCDataChannel")}} 介面用於讓兩端點間建立起資料的通道，你可以利用通道來收發資料。這組 API 被設計成與 <a href="/en-US/docs/Web/API/WebSocket_API">WebSocket API</a> 相似，所以可以利用同樣的程式模型套用在這兩套 API 之上。</dd> +</dl> + +<h2 id="資源">資源</h2> + +<h3 id="Protocols">Protocols</h3> + +<h4 id="WebRTC-proper_protocols">WebRTC-proper protocols</h4> + +<ul> + <li><a href="http://datatracker.ietf.org/doc/draft-ietf-rtcweb-alpn/"><cite>Application Layer Protocol Negotiation for Web Real-Time Communications</cite></a></li> + <li><a href="http://datatracker.ietf.org/doc/draft-ietf-rtcweb-audio/"><cite>WebRTC Audio Codec and Processing Requirements</cite></a></li> + <li><a href="http://datatracker.ietf.org/doc/draft-ietf-rtcweb-data-channel/"><cite>RTCWeb Data Channels</cite></a></li> + <li><a href="http://datatracker.ietf.org/doc/draft-ietf-rtcweb-data-protocol/"><cite>RTCWeb Data Channel Protocol</cite></a></li> + <li><a href="http://datatracker.ietf.org/doc/draft-ietf-rtcweb-rtp-usage/"><cite>Web Real-Time Communication (WebRTC): Media Transport and Use of RTP</cite></a></li> + <li><a href="http://datatracker.ietf.org/doc/draft-ietf-rtcweb-security-arch/"><cite>WebRTC Security Architecture</cite></a></li> + <li><a href="http://datatracker.ietf.org/doc/draft-ietf-rtcweb-transports/"><cite>Transports for RTCWEB</cite></a></li> +</ul> + +<h4 id="Related_supporting_protocols">Related supporting protocols</h4> + +<ul> + <li><a href="https://tools.ietf.org/html/rfc5245">Interactive Connectivity Establishment (ICE): A Protocol for Network Address Translator (NAT) Traversal for Offer/Answer Protocol</a></li> + <li><a href="https://tools.ietf.org/html/rfc5389"><cite>Session Traversal Utilities for NAT (STUN)</cite></a></li> + <li><a href="https://tools.ietf.org/html/rfc7064"><cite>URI Scheme for the Session Traversal Utilities for NAT (STUN) Protocol</cite></a></li> + <li><a href="https://tools.ietf.org/html/rfc7065"><cite>Traversal Using Relays around NAT (TURN) Uniform Resource Identifiers</cite></a></li> + <li><a href="https://tools.ietf.org/html/rfc3264"><cite>An Offer/Answer Model with Session Description Protocol (SDP)</cite></a></li> + <li><a href="https://datatracker.ietf.org/doc/draft-ietf-tram-turn-third-party-authz/"><cite>Session Traversal Utilities for NAT (STUN) Extension for Third Party Authorization</cite></a></li> +</ul> + +<h2 id="規範">規範</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('WebRTC 1.0')}}</td> + <td>{{Spec2('WebRTC 1.0')}}</td> + <td>The initial definition of the API of WebRTC.</td> + </tr> + <tr> + <td>{{SpecName('Media Capture')}}</td> + <td>{{Spec2('Media Capture')}}</td> + <td>The initial definition of the object conveying the stream of media content.</td> + </tr> + <tr> + <td>{{SpecName('Media Capture DOM Elements')}}</td> + <td>{{Spec2('Media Capture DOM Elements')}}</td> + <td>The initial definition on how to obtain stream of content from DOM Elements</td> + </tr> + </tbody> +</table> + +<p>In additions to these specifications defining the API needed to use WebRTC, there are several protocols, listed under <a href="#Protocols">resources</a>.</p> + +<h2 class="Related_Topics" id="參見">參見</h2> + +<ul> + <li>{{domxref("MediaDevices")}}</li> + <li>{{domxref("MediaStreamEvent")}}</li> + <li>{{domxref("MediaStreamConstraints")}}</li> + <li>{{domxref("MediaStreamTrack")}}</li> + <li>{{domxref("MessageEvent")}}</li> + <li>{{domxref("MediaStream")}}</li> + <li><a href="https://hacks.mozilla.org/2015/06/firefox-multistream-and-renegotiation-for-jitsi-videobridge/">Firefox multistream and renegotiation for Jitsi Videobridge</a></li> + <li><a href="https://hacks.mozilla.org/2015/04/peering-through-the-webrtc-fog-with-socketpeer/">Peering Through the WebRTC Fog with SocketPeer</a></li> + <li><a href="https://hacks.mozilla.org/2014/04/inside-the-party-bus-building-a-web-app-with-multiple-live-video-streams-interactive-graphics/">Inside the Party Bus: Building a Web App with Multiple Live Video Streams + Interactive Graphics</a></li> +</ul> diff --git a/files/zh-tw/web/api/webvr_api/index.html b/files/zh-tw/web/api/webvr_api/index.html new file mode 100644 index 0000000000..926a1c3b25 --- /dev/null +++ b/files/zh-tw/web/api/webvr_api/index.html @@ -0,0 +1,246 @@ +--- +title: WebVR API +slug: Web/API/WebVR_API +translation_of: Web/API/WebVR_API +--- +<div>{{SeeCompatTable}}{{APIRef("WebVR API")}}</div> + +<p class="summary">WebVR 可以讓穿戴的VR裝置 (如頭戴裝置 Oculus Rift 或 HTC Vive) 與 web 應用程式結合。開發人員可以將VR裝置所提供的位置與動作資訊轉移到3D的場景中。利用 WebVR可以創造出很多有趣的應用程式: 包含虛擬導覽、互動訓練軟體等等。</p> + +<h2 id="用法與基本觀念">用法與基本觀念</h2> + +<p>透過呼叫 {{domxref("Navigator.getVRDisplays()")}} 函數可以得到與電腦連接的VR裝置，每個裝置會回傳一個 {{domxref("VRDisplay")}} 物件</p> + +<p><img alt='Sketch of a person in a chair with wearing goggles labelled "Head mounted display (HMD)" facing a monitor with a webcam labelled "Position sensor"' src="https://mdn.mozillademos.org/files/11035/hw-setup.png" style="display: block; height: 78px; margin: 0px auto; width: 60%;"></p> + +<p>{{domxref("VRDisplay")}} 是 WebVR API 的核心，提供以下功能:</p> + +<ul> + <li>Retrieve useful information to allow us to identify the display, what capabilities it has, controllers associated with it, and more.</li> + <li>Retrieve {{domxref("VRFrameData", "frame data")}} for each frame of content you you want to present in a display, and submit those frames for display at a consistent rate.</li> + <li>Start and stop presenting to the display.</li> +</ul> + +<p>A typical (simple) WebVR app would work like so:</p> + +<ol> + <li>呼叫 {{domxref("Navigator.getVRDisplays()")}} 來取得 VR 顯示器的 reference。</li> + <li>呼叫 {{domxref("VRDisplay.requestPresent()")}} 來啟動 VR顯示器。</li> + <li>WebVR's dedicated {{domxref("VRDisplay.requestAnimationFrame()")}} method is used to run the app's rendering loop at the correct refresh rate for the display.</li> + <li>Inside the rendering loop, you grab the data required to display the current frame ({{domxref("VRDisplay.getFrameData()")}}), draw the displayed scene twice — once for the view in each eye, then submit the rendered view to the display to show to the user ({{domxref("VRDisplay.submitFrame()")}}).</li> +</ol> + +<p>In addition, WebVR 1.1 adds a number of events on the {{domxref("Window")}} object to allow JavaScript to respond to changes to the status of the display.</p> + +<div class="note"> +<p><strong>Note</strong>: You can find a lot more out about how the API works in our <a href="/en-US/docs/Web/API/WebVR_API/Using_the_WebVR_API">Using the WebVR API</a> and <a href="/en-US/docs/Web/API/WebVR_API/Concepts">WebVR Concepts</a> articles.</p> +</div> + +<h3 id="Using_controllers_Combining_WebVR_with_the_Gamepad_API">Using controllers: Combining WebVR with the Gamepad API</h3> + +<p>Many WebVR hardware setups feature controllers that go along with the headset. These can be used in WebVR apps via the <a href="/en-US/docs/Web/API/Gamepad_API">Gamepad API</a>, and specifically the <a href="/en-US/docs/Web/API/Gamepad_API#Experimental_Gamepad_extensions">Gamepad Extensions API</a> that adds API features for accessing <a href="/en-US/docs/Web/API/GamepadPose">controller pose</a>, <a href="/en-US/docs/Web/API/GamepadHapticActuator">haptic actuators</a>, and more.</p> + +<div class="note"> +<p><strong>Note</strong>: Our <a href="/en-US/docs/Web/API/WebVR_API/Using_VR_controllers_with_WebVR">Using VR controllers with WebVR</a> article explains the basics of how to use VR controllers with WebVR apps.</p> +</div> + +<h2 id="WebVR_Interfaces">WebVR Interfaces</h2> + +<dl> + <dt>{{domxref("VRDisplay")}}</dt> + <dd>Represents any VR device supported by this API. It includes generic information such as device IDs and descriptions, as well as methods for starting to present a VR scene, retrieving eye parameters and display capabilities, and other important functionality.</dd> + <dt>{{domxref("VRDisplayCapabilities")}}</dt> + <dd>Describes the capabilities of a {{domxref("VRDisplay")}} — it's features can be used to perform VR device capability tests, for example can it return position information.</dd> + <dt>{{domxref("VRDisplayEvent")}}</dt> + <dd>Represents the event object of WebVR-related events (see the {{anch("Window", "window object extensions")}} listed below).</dd> + <dt>{{domxref("VRFrameData")}}</dt> + <dd>Represents all the information needed to render a single frame of a VR scene; constructed by {{domxref("VRDisplay.getFrameData()")}}.</dd> + <dt>{{domxref("VRPose")}}</dt> + <dd>Represents the position state at a given timestamp (which includes orientation, position, velocity, and acceleration.)</dd> + <dt>{{domxref("VREyeParameters")}}</dt> + <dd>Provides access to all the information required to correctly render a scene for each given eye, including field of view information.</dd> + <dt>{{domxref("VRFieldOfView")}}</dt> + <dd>Represents a field of view defined by 4 different degree values describing the view from a center point.</dd> + <dt>{{domxref("VRLayerInit")}}</dt> + <dd>Represents a layer to be presented in a {{domxref("VRDisplay")}}.</dd> + <dt>{{domxref("VRStageParameters")}}</dt> + <dd>Represents the values describing the the stage area for devices that support room-scale experiences.</dd> +</dl> + +<h3 id="Extensions_to_other_interfaces">Extensions to other interfaces</h3> + +<p>The WebVR API extends the following APIs, adding the listed features.</p> + +<h4 id="Gamepad">Gamepad</h4> + +<dl> + <dt>{{domxref("Gamepad.displayId")}} {{readonlyInline}}</dt> + <dd><dfn>Returns the {{domxref("VRDisplay.displayId")}} of the associated {{domxref("VRDisplay")}} — the <code>VRDisplay</code> that the gamepad is controlling the displayed scene of.</dfn></dd> +</dl> + +<h4 id="Navigator">Navigator</h4> + +<dl> + <dt>{{domxref("Navigator.activeVRDisplays")}} {{readonlyInline}}</dt> + <dd>Returns an array containing every {{domxref("VRDisplay")}} object that is currently presenting ({{domxref("VRDisplay.ispresenting")}} is <code>true</code>).</dd> + <dt>{{domxref("Navigator.getVRDisplays()")}}</dt> + <dd>Returns a promise that resolves to an array of {{domxref("VRDisplay")}} objects representing any available VR displays connected to the computer.</dd> +</dl> + +<h4 id="Window_events">Window events</h4> + +<dl> + <dt>{{domxref("Window.onvrdisplaypresentchange")}}</dt> + <dd>Represents an event handler that will run when the presenting state of a VR display changes — i.e. goes from presenting to not presenting, or vice versa (when the {{event("vrdisplaypresentchange")}} event fires).</dd> + <dt>{{domxref("Window.onvrdisplayconnect")}}</dt> + <dd>Represents an event handler that will run when a compatible VR display has been connected to the computer (when the {{event("vrdisplayconnect")}} event fires).</dd> + <dt>{{domxref("Window.onvrdisplaydisconnect")}}</dt> + <dd>Represents an event handler that will run when a compatible VR display has been disconnected from the computer (when the {{event("vrdisplaydisconnect")}} event fires).</dd> + <dt>{{domxref("Window.onvrdisplayactivate")}}</dt> + <dd>Represents an event handler that will run when a display is able to be presented to (when the {{event("vrdisplayactivate")}} event fires), for example if an HMD has been moved to bring it out of standby, or woken up by being put on.</dd> + <dt>{{domxref("Window.onvrdisplaydeactivate")}}</dt> + <dd>Represents an event handler that will run when a display can no longer be presented to (when the {{event("vrdisplaydeactivate")}} event fires), for example if an HMD has gone into standby or sleep mode due to a period of inactivity.</dd> +</dl> + +<h4 id="Unimplemented_window_events">Unimplemented window events</h4> + +<p>The following events are listed in the spec, but do not currently seem to be implemented anywhere as yet.</p> + +<dl> + <dt>{{domxref("Window.onvrdisplayblur")}}</dt> + <dd>Represents an event handler that will run when presentation to a display has been paused for some reason by the browser, OS, or VR hardware (when the {{event("vrdisplayblur")}} event fires) — for example, while the user is interacting with a system menu or browser, to prevent tracking or loss of experience.</dd> + <dt>{{domxref("Window.onvrdisplayfocus")}}</dt> + <dd>Represents an event handler that will run when presentation to a display has resumed after being blurred (when the {{event("vrdisplayfocus")}} event fires).</dd> +</dl> + +<h2 id="Examples">Examples</h2> + +<p>You can find a number of examples at these locations:</p> + +<ul> + <li><a href="https://github.com/mdn/webvr-tests">webvr-tests</a> — very simple examples to accompany the MDN WebVR documentation.</li> + <li><a href="https://github.com/facebook/Carmel-Starter-Kit">Carmel starter kit</a> — nice simple, well-commented examples that go along with Carmel, Facebook's WebVR browser.</li> + <li><a href="https://webvr.info/samples/">WebVR.info samples</a> — slightly more in-depth examples plus source code</li> + <li><a href="https://webvr.rocks/firefox#demos">WebVR.rocks Firefox demos</a> — showcase examples</li> + <li><a href="https://aframe.io/">A-Frame homepage</a> — examples showing A-Frame usage</li> +</ul> + +<h2 id="Specifications">Specifications</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("GamepadExtensions")}}</td> + <td>{{Spec2("GamepadExtensions")}}</td> + <td>Defines the <a href="/en-US/docs/Web/API/Gamepad_API#Experimental_Gamepad_extensions">Experimental Gamepad extensions</a>.</td> + </tr> + <tr> + <td>{{SpecName('WebVR 1.1')}}</td> + <td>{{Spec2('WebVR 1.1')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{CompatibilityTable}}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatNo}}<sup>[1]</sup></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop(55)}}<sup>[2]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>Gamepad extensions</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}<sup>[4]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</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>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + <th>Chrome for Android</th> + <th>Samsung Internet for GearVR</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile(55)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}<sup>[3]</sup></td> + <td>{{CompatVersionUnknown}}<br> + </td> + </tr> + <tr> + <td>Gamepad extensions</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}<sup>[4]</sup></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] API Available on all platforms behind a flag, but currently only works on desktop in an <a href="https://webvr.info/get-chrome/">experimental version of Chrome</a> (other builds won't return any devices when {{domxref("Navigator.getVRDisplays()")}} is invoked).</p> + +<p>[2] Currently only Windows support is enabled by default. Mac support is <a href="https://hacks.mozilla.org/2017/06/announcing-webvr-on-mac/">available in Firefox Nightly</a>.</p> + +<p>[3] Currently supported only by Google Daydream.</p> + +<p>[4] Enabled in Firefox Nightly and Beta, versions 55 and above. Enabled/disabled by the <code>dom.gamepad-extensions.enabled</code> pref.</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="https://vr.mozilla.org">vr.mozilla.org</a> — The main Mozilla landing pad for WebVR, with demos, utilities, and other information.</li> + <li><a href="https://aframe.io/">A-Frame</a> — Open source web framework for building VR experiences.</li> + <li><a href="https://webvr.info">webvr.info</a> — Up-to-date information about WebVR, browser setup, and community.</li> + <li><a href="http://mozvr.com/">MozVr.com</a> — Demos, downloads, and other resources from the Mozilla VR team.</li> + <li><a href="https://github.com/MozVR/vr-web-examples/tree/master/threejs-vr-boilerplate">threejs-vr-boilerplate</a> — A useful starter template for writing WebVR apps into.</li> + <li><a href="https://github.com/googlevr/webvr-polyfill/">Web VR polyfill</a> — JavaScript implementation of WebVR.</li> +</ul> diff --git a/files/zh-tw/web/api/wheelevent/index.html b/files/zh-tw/web/api/wheelevent/index.html new file mode 100644 index 0000000000..e7446cc044 --- /dev/null +++ b/files/zh-tw/web/api/wheelevent/index.html @@ -0,0 +1,196 @@ +--- +title: WheelEvent +slug: Web/API/WheelEvent +translation_of: Web/API/WheelEvent +--- +<p>{{APIRef("DOM Events")}}</p> + +<p>WheelEvent DOM事件會在用戶滚动滑鼠滚轮或操作其它類似滑鼠的設備時觸發。</p> + +<div class="warning"><strong>該事件爲標準規定的事件介面。</strong>早期的瀏覽器實現過{{ domxref("MouseWheelEvent") }}和{{domxref("MouseScrollEvent")}}兩種滾輪事件介面，但這兩種介面皆非標準，加之各瀏覽器間對其相容性極差。因而開發者應用該標準事件介面取代這兩個非標準介面。</div> + +<div class="note"><strong>注意事項：</strong> 請勿想當然依據滾輪方向（即該事件的各delta屬性值）來推斷文檔內容的滾動方向，因標準未定義滾輪事件具體會引發什麼樣的行爲，引發的行爲實際上是各瀏覽器自行定義的。即便滾輪事件引發了文檔內容的滾動行爲，也不表示滾輪方向和文檔內容的滾動方向一定相同。因而通過該滾輪事件獲知文檔內容滾動方向的方法並不可靠。要獲取文檔內容的滾動方向，可在文檔內容滾動事件（{{event("scroll")}}）中監視{{domxref("Element.scrollLeft", "scrollLeft")}}和{{domxref("Element.scrollTop", "scrollTop")}}二值變化情況，即可推斷出滾動方向了。</div> + +<p>{{InheritanceDiagram}}</p> + +<h2 id="建構式">建構式</h2> + +<dl> + <dt>{{domxref("WheelEvent.WheelEvent", "WheelEvent()")}}</dt> + <dd>建立一個<code>WheelEvent</code>物件。</dd> +</dl> + +<h2 id="屬性">屬性</h2> + +<p><em>該介面繼承了父介面{{domxref("MouseEvent")}}、{{domxref("UIEvent")}}、{{domxref("Event")}}的屬性。</em></p> + +<dl id="raw_prop"> + <dt>{{domxref("WheelEvent.deltaX")}} {{readonlyinline}}</dt> + <dd>返回<code>double</code>值，該值表示滾輪的橫向滾動量。</dd> + <dt>{{domxref("WheelEvent.deltaY")}} {{readonlyinline}}</dt> + <dd>返回<code>double</code>值，該值表示滾輪的縱向滾動量。</dd> + <dt>{{domxref("WheelEvent.deltaZ")}} {{readonlyinline}}</dt> + <dd>返回<code>double</code>值，該值表示滾輪的z軸方向上的滾動量。</dd> + <dt>{{domxref("WheelEvent.deltaMode")}} {{readonlyinline}}</dt> + <dd>返回<code>unsigned long</code>值，該值表示上述各delta的值的單位。該值及所表示的單位如下： + <table class="standard-table"> + <tbody> + <tr> + <td class="header">常數</td> + <td class="header">值</td> + <td class="header">描述</td> + </tr> + <tr> + <td><code>DOM_DELTA_PIXEL</code></td> + <td><code>0x00</code></td> + <td>滾動量單位爲像素。</td> + </tr> + <tr> + <td><code>DOM_DELTA_LINE</code></td> + <td><code>0x01</code></td> + <td>滾動量單位爲行。</td> + </tr> + <tr> + <td><code>DOM_DELTA_PAGE</code></td> + <td><code>0x02</code></td> + <td>滾動量單位爲頁。</td> + </tr> + </tbody> + </table> + </dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>該介面本身未定義方法，但繼承了父介面{{domxref("MouseEvent")}}、{{domxref("UIEvent")}}、{{domxref("Event")}}的方法。</em></p> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">註解</th> + </tr> + <tr> + <td>{{SpecName('DOM3 Events','#interface-wheelevent','WheelEvent')}}</td> + <td>{{Spec2('DOM3 Events')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>功能</th> + <th>Chrome</th> + <th>Edge</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari (WebKit)</th> + </tr> + <tr> + <td>基本功能</td> + <td>31</td> + <td>{{ CompatVersionUnknown }}</td> + <td>{{ CompatGeckoDesktop("17.0") }}</td> + <td>{{ CompatIE("9.0") }}</td> + <td>18</td> + <td>7.0</td> + </tr> + <tr> + <td><code>window.WheelEvent</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{ CompatVersionUnknown }}</td> + <td>{{ CompatGeckoDesktop("17.0") }}</td> + <td>{{ CompatIE("9.0") }}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}} [1]</td> + </tr> + <tr> + <td><code>WheelEvent</code> + <kbd>Ctrl</kbd> 鍵<sup>[2]</sup>實現按住縮放功能</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{ CompatGeckoDesktop("55.0") }}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>功能</th> + <th>Android</th> + <th>Android Webview</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + <th>Chrome for Android</th> + </tr> + <tr> + <td>基本功能</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{ CompatGeckoMobile("17.0") }}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>window.WheelEvent</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{ CompatGeckoMobile("17.0") }}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>WheelEvent</code> + <kbd>Ctrl</kbd> 鍵<sup>[2]</sup>實現按住縮放功能</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{ CompatGeckoMobile("55.0") }}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] 嚴格說，Safari並非真正支援<code>WheelEvent</code>，只不過會返回window.WheelEvent物件。</p> + +<p>[2] 這樣在觸控平面上，比如觸控螢幕或是觸控板上，開發者就可根據用戶按住縮放手勢來實現簡單的縮放功能 (滑鼠滾輪 + <kbd>Ctrl</kbd> 習慣上用於縮放)。</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{ event("wheel") }}</li> + <li>該介面取代的過時介面： + <ul> + <li>{{ domxref("MouseScrollEvent") }}（Gecko內核瀏覽器）</li> + <li>{{ domxref("MouseWheelEvent") }}（非Gecko內核的瀏覽器）</li> + </ul> + </li> +</ul> diff --git a/files/zh-tw/web/api/window.history/index.html b/files/zh-tw/web/api/window.history/index.html new file mode 100644 index 0000000000..67b79c5f82 --- /dev/null +++ b/files/zh-tw/web/api/window.history/index.html @@ -0,0 +1,51 @@ +--- +title: Window.history +slug: Web/API/Window.history +translation_of: Web/API/Window/history +--- +<p>{{ APIRef }}</p> + +<p><code><strong>Window</strong>.<strong>history</strong></code> 唯讀屬性會回傳一個 {{domxref("History")}} 物件，其提供了一個介面來操控瀏覽器的 <em>session history</em> 紀錄（為當前面頁所在分頁中訪問、或於當前面頁中透過頁面框架（frame）所載入的頁面）。</p> + +<p>相關範例及細節請參考<a href="/zh-TW/docs/Web/API/History_API">操控瀏覽器歷史紀錄</a>一文。文章中解釋了在使用 <code>pushState()</code> 與 <code>replaceState()</code> 方法前應該要知道的安全性功能。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><em>var historyObj</em> = <em>window</em>.history; +</pre> + +<h2 id="範例">範例</h2> + +<pre class="brush: js">history.back(); // 相當於按下上一頁按鈕 +history.go(-1); // 相當於 history.back(); +</pre> + +<h2 id="備註">備註</h2> + +<p>For top-level pages you can see the list of pages in the session history, accessible via the <code>History</code> object, in the browser's dropdowns next to the back and forward buttons.</p> + +<p>For security reasons the <code>History</code> object doesn't allow the non-privileged code to access the URLs of other pages in the session history, but it does allow it to navigate the session history.</p> + +<p>There is no way to clear the session history or to disable the back/forward navigation from unprivileged code. The closest available solution is the <code><a href="/en/DOM/window.location#replace" title="en/DOM/window.location#replace">location.replace()</a></code> method, which replaces the current item of the session history with the provided URL.</p> + +<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('HTML WHATWG', 'browsers.html#the-history-interface', 'The History interface')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', 'browsers.html#the-history-interface', 'The History interface')}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td> </td> + </tr> + </tbody> +</table> diff --git a/files/zh-tw/web/api/window.onpopstate/index.html b/files/zh-tw/web/api/window.onpopstate/index.html new file mode 100644 index 0000000000..d98464d356 --- /dev/null +++ b/files/zh-tw/web/api/window.onpopstate/index.html @@ -0,0 +1,57 @@ +--- +title: window.onpopstate +slug: Web/API/Window.onpopstate +translation_of: Web/API/WindowEventHandlers/onpopstate +--- +<div>{{ApiRef}} {{gecko_minversion_header("2")}}</div> + +<h2 id="Summary" name="Summary">摘要</h2> + +<p>視窗上 popstate 事件的事件處理器。</p> + +<p>在同一文件的當前歷史紀錄變動時，如果其變動介於兩個歷史紀錄間，<code>popstate</code> 就會被呼叫。如果當前的歷史紀錄是藉由呼叫 <code>history.pushState() </code>建立，或曾被 <code>history.replaceState() 修改過，popstate </code>事件的 <code>state</code> 屬性，將包含一份歷史紀錄的 state 物件。</p> + +<p>請注意：直接呼叫 <code>history.pushState()</code> 或 <code>history.replaceState()</code> 不會驅動 <code>popstate</code> 事件。<code>popstate</code> 事件只會被瀏覽器的行為驅動，例如點擊上一頁按鈕（或透過 JavaScript 呼叫 <code>history.back()</code>）。且此事件只會在用戶於同文件的兩個歷史紀錄間瀏覽時作動。</p> + +<p>在頁面載入時，不同瀏覽器具有不同的 <code>popstate</code> 行為。Chrome 與 Safari 會在頁面載入時觸發 <code>popstate</code> 事件，但 Firefox 則不會。</p> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox">window.onpopstate = <var>funcRef</var>; +</pre> + +<ul> + <li><var>funcRef</var> 是一個事件處理函數</li> +</ul> + +<h2 id="The_popstate_event" name="The_popstate_event">popstate 事件</h2> + +<p>以下範例，位於 <code><var>http://example.com/example.html</var></code> 並執行下列程式的頁面，將會產生如標示的對話框：</p> + +<pre class="brush: js">window.onpopstate = function(event) { + alert("location: " + document.location + ", state: " + JSON.stringify(event.state)); +}; + +history.pushState({page: 1}, "title 1", "?page=1"); +history.pushState({page: 2}, "title 2", "?page=2"); +history.replaceState({page: 3}, "title 3", "?page=3"); +history.back(); // 跳出 "location: http://example.com/example.html?page=1, state: {"page":1}" +history.back(); // 跳出 "location: http://example.com/example.html, state: null +history.go(2); // 跳出 "location: http://example.com/example.html?page=3, state: {"page":3} +</pre> + +<p><span style="line-height: inherit;">請注意，</span><span style="line-height: inherit;">雖然原始的歷史紀錄（</span><code><var>http://example.com/example.html</var></code><span style="line-height: inherit;">）沒有關聯的 state 物件，在我們第二次呼叫 </span><code style="font-size: 14px; line-height: inherit;">hitsory.back() 時仍然會觸發</code><code style="font-size: 14px; line-height: inherit;"> </code><code style="font-size: 14px; line-height: inherit;">popstate</code><span style="line-height: inherit;"> 事件</span><span style="line-height: inherit;">。</span></p> + +<h2 id="Specification" name="Specification">標準</h2> + +<ul> + <li><a href="http://www.whatwg.org/specs/web-apps/current-work/#handler-window-onpopstate">HTML5 popstate event</a></li> +</ul> + +<h2 id="See_also" name="See_also">請參照</h2> + +<ul> + <li>{{domxref("window.history")}}</li> + <li><a href="/en-US/docs/Web/Guide/DOM/Manipulating_the_browser_history">Manipulating the browser history</a></li> + <li><a href="/en-US/docs/Web/Guide/DOM/Manipulating_the_browser_history/Example">Ajax navigation example</a></li> +</ul> diff --git a/files/zh-tw/web/api/window.requestanimationframe/index.html b/files/zh-tw/web/api/window.requestanimationframe/index.html new file mode 100644 index 0000000000..55aa85d292 --- /dev/null +++ b/files/zh-tw/web/api/window.requestanimationframe/index.html @@ -0,0 +1,94 @@ +--- +title: Window.requestAnimationFrame() +slug: Web/API/Window.requestAnimationFrame +translation_of: Web/API/window/requestAnimationFrame +--- +<div>{{APIRef}}</div> + +<p><strong><code>window.requestAnimationFrame()</code></strong>方法通知瀏覽器我們想要產生動畫，並且要求瀏覽器在下次重繪畫面前呼叫特定函數更新動畫。這個方法接受一個引數作為下次重繪前調用的回呼函數。</p> + +<div class="note"><strong>Note:</strong> 若是想要在下次重繪時產生另一個動畫，這個回呼函數內必須自行呼叫 requestAnimationFrame()。</div> + +<p>當準備好更新頁面上的動畫時應當呼叫這個方法。這表示向瀏覽器請求在下次重繪前呼叫這個動畫函數。回呼的次數通常落在每秒 60 次，但通常會根據 W3C 的建議符合多數瀏覽器重新整理的頻率。當頁面處於背景或隱藏狀態時 {{ HTMLElement("iframe") }} ，多數的瀏覽器會暫停 <code>requestAnimationFrame()</code> 的呼叫，從而改善效能表現及電池壽命。</p> + +<p>回呼方法會得到一個 {{domxref("DOMHighResTimeStamp")}} 的引數，作為指示目前的時間（基於 <a href="/en-US/docs/Web/API/DOMHighResTimeStamp#The_time_origin">time origin</a> 之後經過的毫秒數）。當 <code>requestAnimationFrame()</code> 佇列了數個回呼並且在同一幀開始觸發多個回呼時，儘管每一個之前的回呼在運作時會消耗一定的時間，但它們都會取得同樣的時間戳記。時間戳記是由十進位數字表示的毫秒且最小的精準度為 1 毫秒（1000 µs）。</p> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox">window.requestAnimationFrame(callback); +</pre> + +<h3 id="Parameters" name="Parameters">參數</h3> + +<dl> + <dt><code>回呼</code></dt> + <dd>當下次重新繪製時用於呼叫並更新動畫。回呼函數會得到一個引數—— {{domxref("DOMHighResTimeStamp")}} ——類似於由 {{domxref('performance.now()')}} 回傳的結果，其用於指示當 <code>requestAnimationFrame()</code> 開始執行回呼函數的時間。</dd> +</dl> + +<h3 id="回傳值">回傳值</h3> + +<p><code>long</code> 型別的整數值表示請求的 id，作為其進入回呼清單中的唯一識別。雖然回傳值是一個非零值，但不應該對其有其他任何的假設。將這個值傳遞給 {{domxref("window.cancelAnimationFrame()")}} 可以取消重新整理頁面回呼的請求</p> + +<h2 id="Notes" name="Notes">範例</h2> + +<pre class="brush: js">var start = null; +var element = document.getElementById('SomeElementYouWantToAnimate'); + +function step(timestamp) { + if (!start) start = timestamp; + var progress = timestamp - start; + element.style.transform = 'translateX(' + Math.min(progress / 10, 200) + 'px)'; + if (progress < 2000) { + window.requestAnimationFrame(step); + } +} + +window.requestAnimationFrame(step); +</pre> + +<h2 id="備註">備註</h2> + +<p>Edge 低於 17 的版本和 Internet Explorer 無法保證在繪製循環前觸發 <code>requestAnimationFrame</code>。</p> + +<h2 id="Specification" name="Specification">規格</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', '#animation-frames', 'requestAnimationFrame')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>No change, supersedes the previous one.</td> + </tr> + <tr> + <td>{{SpecName('RequestAnimationFrame', '#dom-windowanimationtiming-requestanimationframe', 'requestAnimationFrame')}}</td> + <td>{{Spec2('RequestAnimationFrame')}}</td> + <td>Initial definition</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<div> +<p>{{Compat("api.Window.requestAnimationFrame")}}</p> +</div> + +<h2 id="See_also" name="See_also">其他參考</h2> + +<ul> + <li>{{domxref("Window.mozAnimationStartTime")}}</li> + <li>{{domxref("Window.cancelAnimationFrame()")}}</li> + <li><a href="http://weblogs.mozillazine.org/roc/archives/2010/08/mozrequestanima.html">mozRequestAnimationFrame</a> - Blog post</li> + <li><a href="http://paulirish.com/2011/requestanimationframe-for-smart-animating/">requestAnimationFrame for smart animating</a> - Blog post</li> + <li><a href="http://hacks.mozilla.org/2011/08/animating-with-javascript-from-setinterval-to-requestanimationframe/">Animating with javascript: from setInterval to requestAnimationFrame</a> - Blog post</li> + <li><a href="http://blogs.msdn.com/b/ie/archive/2011/07/05/using-pc-hardware-more-efficiently-in-html5-new-web-performance-apis-part-1.aspx">Using PC Hardware more efficiently in HTML5: New Web Performance APIs, Part 1</a> - Blog post</li> + <li><a href="http://www.testufo.com/#test=animation-time-graph" title="http://www.testufo.com/#test=animation-time-graph">TestUFO: Test your web browser for requestAnimationFrame() Timing Deviations</a></li> + <li>Paul Irish: <a class="external external-icon" href="http://updates.html5rocks.com/2012/05/requestAnimationFrame-API-now-with-sub-millisecond-precision">requestAnimationFrame API: now with sub-millisecond precision</a></li> +</ul> diff --git a/files/zh-tw/web/api/window/getcomputedstyle/index.html b/files/zh-tw/web/api/window/getcomputedstyle/index.html new file mode 100644 index 0000000000..8dd0f24bad --- /dev/null +++ b/files/zh-tw/web/api/window/getcomputedstyle/index.html @@ -0,0 +1,200 @@ +--- +title: Window.getComputedStyle() +slug: Web/API/Window/getComputedStyle +translation_of: Web/API/Window/getComputedStyle +--- +<p>{{APIRef()}}</p> + +<h2 id="概要">概要</h2> + +<p><code>Window.getComputedStyle()</code> 方法可以得到元素於套用啟用之樣式表以及解析其中可能包含的任何基本運算後的所有 CSS 屬性值。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">var <em>style</em> = window.getComputedStyle(<em>element</em>[, <em>pseudoElt</em>]); +</pre> + +<dl> + <dt>element</dt> + <dd>The {{domxref("Element")}} for which to get the computed style.</dd> + <dt>pseudoElt {{optional_inline}}</dt> + <dd>A string specifying the pseudo-element to match. Must be omitted (or <code>null</code>) for regular elements.</dd> +</dl> + +<div class="note"><strong>Note:</strong> Prior to Gecko 2.0 {{geckoRelease("2.0")}}, the <code>pseudoElt</code> parameter was required. No other major browser required this parameter be specified if null. Gecko has been changed to match the behavior of other browsers.</div> + +<p>The returned <code>style</code> is a <em>live</em> {{domxref("CSSStyleDeclaration")}} object, which updates itself automatically when the element's style is changed.</p> + +<h2 id="範例">範例</h2> + +<pre class="brush: js">var elem1 = document.getElementById("elemId"); +var style = window.getComputedStyle(elem1, null); + +// this is equivalent: +// var style = document.defaultView.getComputedStyle(elem1, null); +</pre> + +<pre class="brush: js"><style> + #elem-container{ + position: absolute; + left: 100px; + top: 200px; + height: 100px; + } +</style> + +<div id="elem-container">dummy</div> +<div id="output"></div> + +<script> + function getTheStyle(){ + var elem = document.getElementById("elem-container"); + var theCSSprop = window.getComputedStyle(elem,null).getPropertyValue("height"); + document.getElementById("output").innerHTML = theCSSprop; + } + getTheStyle(); +</script> +</pre> + +<pre class="brush: js">function dumpComputedStyles(elem,prop) { + + var cs = window.getComputedStyle(elem,null); + if (prop) { + console.log(prop+" : "+cs.getPropertyValue(prop)); + return; + } + var len = cs.length; + for (var i=0;i<len;i++) { + + var style = cs[i]; + console.log(style+" : "+cs.getPropertyValue(style)); + } + +} +</pre> + +<h2 id="說明">說明</h2> + +<p>The returned object is of the same type that the object returned from the element's {{domxref("HTMLElement.style", "style")}} property; however, the two objects have different purposes. The object returned from<code> getComputedStyle </code>is read-only and can be used to inspect the element's style (including those set by a <code><style></code> element or an external stylesheet). The<code> elt.style</code> object should be used to set styles on a specific element.</p> + +<p>The first argument must be an Element (passing a non-Element Node, like a #text Node, will throw an error). Starting in Gecko 1.9.2 {{geckoRelease("1.9.2")}}, returned URL values now have quotes around the URL, like this: <code>url("http://foo.com/bar.jpg")</code>.</p> + +<h2 id="defaultView"><code>defaultView</code></h2> + +<p>In many code samples online, <code>getComputedStyle</code> is used from the <code>document.defaultView</code> object. In nearly all cases, this is needless, as <code>getComputedStyle</code> exists on the <code>window</code> object as well. It's likely the defaultView pattern was some combination of (1) folks not wanting to write a spec for window and (2) making an API that was also usable in Java. However, there is <a class="link-https" href="https://github.com/jquery/jquery/pull/524#issuecomment-2241183" title="https://github.com/jquery/jquery/pull/524#issuecomment-2241183">a single case</a> where the <code>defaultView</code>'s method must be used: when using Firefox 3.6 to access framed styles.</p> + +<h2 id="Use_with_pseudo-elements">Use with pseudo-elements</h2> + +<p>getComputedStyle can pull style info from pseudo-elements (for example, <code>::after</code>, <code>::before</code>, <code>::marker</code>, <code>::line-marker</code>—see <a class="external" href="http://dev.w3.org/csswg/css3-content/#pseudo-elements">spec</a> here).</p> + +<pre class="brush: html"><style> + h3::after { + content: ' rocks!'; + } +</style> + +<h3>generated content</h3> + +<script> + var h3 = document.querySelector('h3'), + result = getComputedStyle(h3, ':after').content; + + console.log('the generated content is: ', result); // returns ' rocks!' +</script> +</pre> + +<h2 id="備註">備註</h2> + +<p>The values returned by <code>getComputedStyle</code> are known as {{cssxref("resolved_value", "resolved values")}}. These are usually the same as the CSS 2.1 {{cssxref("computed_value","computed values")}}, but for some older properties like <code>width</code>, <code>height</code> or <code>padding</code>, they are instead the {{cssxref("used_value","used values")}}. Originally, CSS 2.0 defined the computed values to be the "ready to be used" final values of properties after cascading and inheritance, but CSS 2.1 redefined computed values as pre-layout, and used values as post-layout. For CSS 2.0 properties, the <code>getComputedStyle</code> function returns the old meaning of computed values, now called <strong>used values</strong>. An example of difference between pre- and post-layout values includes the resolution of percentages that represent the width or the height of an element (also known as its layout), as those will be replaced by their pixel equivalent only in the used value case.</p> + +<p>The returned value is, in certain known cases, expressly inaccurate by deliberate intent. In particular, to avoid the so called CSS History Leak security issue, browsers may expressly "lie" about the used value for a link and always return values as if a user has never visited the linked site. See <a class="external" href="http://blog.mozilla.com/security/2010/03/31/plugging-the-css-history-leak/">http://blog.mozilla.com/security/2010/03/31/plugging-the-css-history-leak/</a> and <a class="external" href="http://hacks.mozilla.org/2010/03/privacy-related-changes-coming-to-css-vistited/">http://hacks.mozilla.org/2010/03/privacy-related-changes-coming-to-css-vistited/</a> for details of the examples of how this is implemented. Most other modern browsers have applied similar changes to the application of pseudo-selector styles and the values returned by <code>getComputedStyle</code>.</p> + +<p>During a CSS transition, <code>getComputedStyle</code> returns the original property value in Firefox, but the final property value in WebKit.</p> + +<p>In Firefox, properties with the value <code>auto</code> return the used value, not the value <code>auto</code>. So if you apply <code>top:auto;</code> and <code>bottom:0</code>; on an element with <code>height:30px</code> and its containing block is <code>height:100px;</code>, upon requesting the computed style for <code>top</code>, Firefox will return <code>top:70px</code>, as <code>100px-30px=70px</code>.</p> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>9</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>pseudo-element support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>9</td> + <td>15</td> + <td>{{CompatVersionUnknown}} </td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>WP7 Mango</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>pseudo-element support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="規範">規範</h2> + +<ul> + <li><a class="external" href="https://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSview-getComputedStyle">DOM Level 2 Style: getComputedStyle</a></li> + <li><a href="https://drafts.csswg.org/cssom/#dom-window-getcomputedstyle" title="https://drafts.csswg.org/cssom/#dom-window-getcomputedstyle">CSS Object Model specification</a></li> +</ul> + +<h2 id="See_also" name="See_also">參見</h2> + +<ul> + <li>{{domxref("window.getDefaultComputedStyle")}}</li> + <li>{{cssxref("resolved_value", "Resolved Value")}}</li> +</ul> diff --git a/files/zh-tw/web/api/window/index.html b/files/zh-tw/web/api/window/index.html new file mode 100644 index 0000000000..276dcc96e2 --- /dev/null +++ b/files/zh-tw/web/api/window/index.html @@ -0,0 +1,468 @@ +--- +title: Window +slug: Web/API/Window +translation_of: Web/API/Window +--- +<p>{{APIRef}}</p> + +<p><span class="seoSummary"><code>window</code> 物件代表了一個包含 DOM 文件的視窗，其中的 <code>document</code> 屬性指向了視窗中載入的 {{domxref("Document")}} 物件。而使用 <code>document</code> 的</span> {{Domxref("Document.defaultView", "defaultView")}} 屬性，則可取得該 Document 物件所在的視窗 <code>window</code> 物件。</p> + +<p>本節提供了 DOM <code>window</code> 物件的所有方法、屬性以及事件的說明。<code>window</code> 物件實作了 <code>Window</code> 介面，而 <code>Window</code> 介面則繼承自 <code><a href="http://www.w3.org/TR/DOM-Level-2-Views/views.html#Views-AbstractView">AbstractView</a></code> 介面。一些額外、與 <code>window</code> 物件沒有直接關係，但卻置於 <code>window</code> 物件中的全域函式、命名空間、物件、介面以及建構式，將會在 <a href="/zh-TW/docs/JavaScript/Reference">JavaScript 參考文件</a>和<a href="/zh-TW/docs/Web/API/Document_Object_Model">文件物件模型（DOM）</a>中說明。</p> + +<p>在支援分頁的瀏覽器中（如 Firefox），每一個分頁標籤都擁有自己的 <code>window</code> 物件（如果你正在撰寫瀏覽器附加元件，瀏覽器視窗本身也是一個個別的 window－請參閱 <a href="/zh-TW/docs/Working_with_windows_in_chrome_code#Content_windows">Working with windows in chrome code</a>），分頁不會於同一個瀏覽器視窗中共享 <code>window</code> 物件。但有部分的方法，如 {{Domxref("window.resizeTo()")}} 或 {{Domxref("window.resizeBy()")}} 會套用至整個視窗，而不只是該 <code>window</code> 物件所屬的分頁標籤。一般來說，若無法適當的應用於分頁，便會套用至瀏覽器視窗。</p> + +<p>{{InheritanceDiagram}}</p> + +<h2 id="屬性">屬性</h2> + +<p><em>This interface inherits properties from the {{domxref("EventTarget")}} interface and implements properties from the {{domxref("WindowOrWorkerGlobalScope")}} and {{domxref("WindowEventHandlers")}} mixins.</em></p> + +<p>請注意，指向物件的屬性（例如覆蓋了內建物件原型的元素）會在另外的列表中說明。</p> + +<dl> + <dt>{{domxref("Window.applicationCache")}} {{readOnlyInline}} {{gecko_minversion_inline("1.9")}}</dt> + <dd>指向 {{domxref("OfflineResourceList")}} 物件，此物件提供了視窗的離線資源。</dd> + <dt>{{domxref("Window.closed")}} {{Non-standard_inline}}{{readOnlyInline}}</dt> + <dd>This property indicates whether the current window is closed or not.</dd> + <dt>{{domxref("Window.Components")}} {{Non-standard_inline}}</dt> + <dd>The entry point to many <a href="/zh-TW/docs/XPCOM">XPCOM</a> features. Some properties, e.g. <a href="/zh-TW/docs/Components.classes">classes</a>, are only available to sufficiently privileged code. <strong>Web code should not use this property.</strong></dd> + <dt>{{domxref("Window.console")}} {{ReadOnlyInline}}</dt> + <dd>Returns a reference to the console object which provides access to the browser's debugging console.</dd> + <dt>{{domxref("Window.content")}} and Window._content {{Non-standard_inline}} {{obsolete_inline}}{{ReadOnlyInline}}</dt> + <dd>Returns a reference to the content element in the current window. The obsolete variant with underscore is no longer available from Web content.</dd> + <dt>{{domxref("Window.controllers")}}{{non-standard_inline}}{{ReadOnlyInline}}</dt> + <dd>Returns the XUL controller objects for the current chrome window.</dd> + <dt>{{domxref("Window.crypto")}} {{readOnlyInline}}</dt> + <dd>Returns the browser crypto object.</dd> + <dt>{{domxref("Window.defaultStatus")}} {{Obsolete_inline("gecko23")}}</dt> + <dd>Gets/sets the status bar text for the given window.</dd> + <dt>{{domxref("Window.devicePixelRatio")}} {{non-standard_inline}}{{ReadOnlyInline}}</dt> + <dd>Returns the ratio between physical pixels and device independent pixels in the current display.</dd> + <dt>{{domxref("Window.dialogArguments")}} {{Fx_minversion_inline(3)}} {{ReadOnlyInline}}</dt> + <dd>Gets the arguments passed to the window (if it's a dialog box) at the time {{domxref("window.showModalDialog()")}} was called. This is an {{Interface("nsIArray")}}.</dd> + <dt>{{domxref("Window.directories")}} {{obsolete_inline}}</dt> + <dd>Synonym of {{domxref("window.personalbar")}}</dd> + <dt>{{domxref("Window.document")}} {{ReadOnlyInline}}</dt> + <dd>指向此 <code>window</code> 中的 <code>document</code> 物件。</dd> + <dt>{{domxref("Window.frameElement")}} {{readOnlyInline}}</dt> + <dd>Returns the element in which the window is embedded, or null if the window is not embedded.</dd> + <dt>{{domxref("Window.frames")}} {{readOnlyInline}}</dt> + <dd>Returns an array of the subframes in the current window.</dd> + <dt>{{domxref("Window.fullScreen")}} {{gecko_minversion_inline("1.9")}}</dt> + <dd>此屬性表示目前視窗是否為全螢幕顯示。</dd> + <dt>{{domxref("Window.globalStorage")}} {{gecko_minversion_inline("1.8.1")}} {{Non-standard_inline}} {{Obsolete_inline("gecko13")}}</dt> + <dd>Unsupported since Gecko 13 (Firefox 13). Use {{domxref("Window.localStorage")}} instead.<br> + Was: Multiple storage objects that are used for storing data across multiple pages.</dd> + <dt>{{domxref("Window.history")}} {{ReadOnlyInline}}</dt> + <dd>指向 history 物件。</dd> + <dt>{{domxref("Window.innerHeight")}} {{readOnlyInline}}</dt> + <dd>取得視窗內的網頁內容高度，包含水平捲軸。</dd> + <dt>{{domxref("Window.innerWidth")}} {{readOnlyInline}}</dt> + <dd>取得視窗內的網頁內容寬度，包含垂直捲軸。</dd> + <dt>{{domxref("Window.isSecureContext")}} {{readOnlyInline}}</dt> + <dd>Indicates whether a context is capable of using features that require secure contexts.</dd> + <dt>{{domxref("Window.length")}} {{readOnlyInline}}</dt> + <dd>Returns the number of frames in the window. See also {{domxref("window.frames")}}.</dd> + <dt>{{domxref("Window.location")}}</dt> + <dd>Gets/sets the location, or current URL, of the window object.</dd> + <dt>{{domxref("Window.locationbar")}} {{ReadOnlyInline}}</dt> + <dd>Returns the locationbar object, whose visibility can be toggled in the window.</dd> + <dt>{{domxref("Window.localStorage")}} {{readOnlyInline}}{{gecko_minversion_inline("1.9.1")}}</dt> + <dd>Returns a reference to the local storage object used to store data that may only be accessed by the origin that created it.</dd> + <dt>{{domxref("Window.menubar")}} {{ReadOnlyInline}}</dt> + <dd>Returns the menubar object, whose visibility can be toggled in the window.</dd> + <dt>{{domxref("Window.messageManager")}} {{gecko_minversion_inline("2.0")}}</dt> + <dd>Returns the <a href="/zh-TW/docs/The_message_manager">message manager</a> object for this window.</dd> + <dt>{{domxref("Window.mozAnimationStartTime")}} {{ReadOnlyInline}}{{gecko_minversion_inline("2.0")}} {{Deprecated_inline}}</dt> + <dd>The time in milliseconds since epoch at which the current animation cycle began.</dd> + <dt>{{domxref("Window.mozInnerScreenX")}} {{ReadOnlyInline}}{{non-standard_inline}}{{gecko_minversion_inline("1.9.2")}}</dt> + <dd>Returns the horizontal (X) coordinate of the top-left corner of the window's viewport, in screen coordinates. This value is reported in CSS pixels. See <code>mozScreenPixelsPerCSSPixel</code> in {{interface("nsIDOMWindowUtils")}} for a conversion factor to adapt to screen pixels if needed.</dd> + <dt>{{domxref("Window.mozInnerScreenY")}} {{ReadOnlyInline}} {{non-standard_inline}}{{gecko_minversion_inline("1.9.2")}}</dt> + <dd>Returns the vertical (Y) coordinate of the top-left corner of the window's viewport, in screen coordinates. This value is reported in CSS pixels. See <code>mozScreenPixelsPerCSSPixel</code> for a conversion factor to adapt to screen pixels if needed.</dd> + <dt>{{domxref("Window.mozPaintCount")}} {{non-standard_inline}}{{ReadOnlyInline}} {{gecko_minversion_inline("2.0")}}</dt> + <dd>Returns the number of times the current document has been rendered to the screen in this window. This can be used to compute rendering performance.</dd> + <dt>{{domxref("Window.name")}}</dt> + <dd>Gets/sets the name of the window.</dd> + <dt>{{domxref("Window.navigator")}} {{readOnlyInline}}</dt> + <dd>Returns a reference to the navigator object.</dd> + <dt>{{domxref("Window.opener")}}</dt> + <dd>Returns a reference to the window that opened this current window.</dd> + <dt>{{domxref("Window.orientation")}}{{non-standard_inline}}{{deprecated_inline}}{{readOnlyInline}}</dt> + <dd>Returns the orientation in degrees (in 90 degree increments) of the viewport relative to the device's natural orientation.</dd> + <dt>{{domxref("Window.outerHeight")}} {{readOnlyInline}}</dt> + <dd>取得瀏覽器視窗的高度。</dd> + <dt>{{domxref("Window.outerWidth")}} {{readOnlyInline}}</dt> + <dd>取得瀏覽器視窗的寬度。</dd> + <dt>{{domxref("Window.scrollX","Window.pageXOffset")}} {{readOnlyInline}}</dt> + <dd>An alias for {{domxref("window.scrollX")}}.</dd> + <dt>{{domxref("Window.scrollY","Window.pageYOffset")}}{{readOnlyInline}}</dt> + <dd>An alias for {{domxref("window.scrollY")}}</dd> + <dt>{{domxref("Window.sessionStorage")}} {{readOnlyInline}}</dt> + <dd>Returns a reference to the session storage object used to store data that may only be accessed by the origin that created it.</dd> + <dt>{{domxref("Window.parent")}} {{readOnlyInline}}</dt> + <dd>Returns a reference to the parent of the current window or subframe.</dd> + <dt>{{domxref("Window.performance")}} {{readOnlyInline}}</dt> + <dd>Returns a {{domxref("Performance")}} object, which includes the {{domxref("Performance.timing", "timing")}} and {{domxref("Performance.navigation", "navigation")}} attributes, each of which is an object providing <a href="/zh-TW/docs/Navigation_timing">performance-related</a> data. See also <a href="/zh-TW/docs/Web/API/Navigation_timing_API/Using_Navigation_Timing">Using Navigation Timing</a> for additional information and examples.</dd> + <dt>{{domxref("Window.personalbar")}} {{readOnlyInline}}</dt> + <dd>Returns the personalbar object, whose visibility can be toggled in the window.</dd> + <dt>{{domxref("Window.pkcs11")}} {{obsolete_inline(29)}}</dt> + <dd>Formerly provided access to install and remove PKCS11 modules.</dd> + <dt>{{domxref("Window.returnValue")}} {{Fx_minversion_inline(3)}}</dt> + <dd>The return value to be returned to the function that called {{domxref("window.showModalDialog()")}} to display the window as a modal dialog.</dd> + <dt>{{domxref("Window.screen")}} {{readOnlyInline}}</dt> + <dd>回傳一個與 window 關聯的 screen 物件。</dd> + <dt>{{domxref("Window.screenX")}} {{readOnlyInline}}</dt> + <dd>Returns the horizontal distance of the left border of the user's browser from the left side of the screen.</dd> + <dt>{{domxref("Window.screenY")}} {{readOnlyInline}}</dt> + <dd>Returns the vertical distance of the top border of the user's browser from the top side of the screen.</dd> + <dt>{{domxref("Window.scrollbars")}} {{readOnlyInline}}</dt> + <dd>Returns the scrollbars object, whose visibility can be toggled in the window.</dd> + <dt>{{domxref("Window.scrollMaxX")}}{{non-standard_inline}}{{ReadOnlyInline}}</dt> + <dd>The maximum offset that the window can be scrolled to horizontally, that is the document width minus the viewport width.</dd> + <dt>{{domxref("Window.scrollMaxY")}}{{non-standard_inline}}{{ReadOnlyInline}}</dt> + <dd>The maximum offset that the window can be scrolled to vertically (i.e., the document height minus the viewport height).</dd> + <dt>{{domxref("Window.scrollX")}} {{readOnlyInline}}</dt> + <dd>Returns the number of pixels that the document has already been scrolled horizontally.</dd> + <dt>{{domxref("Window.scrollY")}} {{readOnlyInline}}</dt> + <dd>Returns the number of pixels that the document has already been scrolled vertically.</dd> + <dt>{{domxref("Window.self")}} {{ReadOnlyInline}}</dt> + <dd>Returns an object reference to the window object itself.</dd> + <dt>{{domxref("Window.sessionStorage")}} {{Fx_minversion_inline("2.0")}}</dt> + <dd>Returns a storage object for storing data within a single page session.</dd> + <dt>{{domxref("Window.sidebar")}} {{non-standard_inline}}{{ReadOnlyInline}}</dt> + <dd>Returns a reference to the window object of the sidebar.</dd> + <dt>{{domxref("Window.speechSynthesis")}} {{ReadOnlyInline}}</dt> + <dd>Returns a {{domxref("SpeechSynthesis")}} object, which is the entry point into using <a href="/zh-TW/docs/Web/API/Web_Speech_API">Web Speech API</a> speech synthesis functionality.</dd> + <dt>{{domxref("Window.status")}}</dt> + <dd>Gets/sets the text in the statusbar at the bottom of the browser.</dd> + <dt>{{domxref("Window.statusbar")}} {{readOnlyInline}}</dt> + <dd>Returns the statusbar object, whose visibility can be toggled in the window.</dd> + <dt>{{domxref("Window.toolbar")}} {{readOnlyInline}}</dt> + <dd>Returns the toolbar object, whose visibility can be toggled in the window.</dd> + <dt>{{domxref("Window.top")}} {{readOnlyInline}}</dt> + <dd>Returns a reference to the topmost window in the window hierarchy. This property is read only.</dd> + <dt>{{domxref("Window.window")}} {{ReadOnlyInline}}</dt> + <dd>Returns a reference to the current window.</dd> + <dt><code>window[0]</code>,<code> window[1]</code>, etc.</dt> + <dd>Returns a reference to the <code>window</code> object in the frames. See {{domxref("Window.frames")}} for more details.</dd> +</dl> + +<h3 id="Properties_implemented_from_elsewhere">Properties implemented from elsewhere</h3> + +<dl> + <dt>{{domxref("WindowOrWorkerGlobalScope.caches")}} {{readOnlyinline}}</dt> + <dd>Returns the {{domxref("CacheStorage")}} object associated with the current context. This object enables functionality such as storing assets for offline use, and generating custom responses to requests.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.indexedDB")}} {{readonlyInline}}</dt> + <dd>Provides a mechanism for applications to asynchronously access capabilities of indexed databases; returns an {{domxref("IDBFactory")}} object.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.isSecureContext")}} {{readOnlyinline}}</dt> + <dd>Returns a boolean indicating whether the current context is secure (<code>true</code>) or not (<code>false</code>).</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.origin")}} {{readOnlyinline}}</dt> + <dd>Returns the global object's origin, serialized as a string. (This does not yet appear to be implemented in any browser.)</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>This interface inherits methods from the {{domxref("EventTarget")}} interface and implements methods from {{domxref("WindowOrWorkerGlobalScope")}} and {{domxref("EventTarget")}}.</em></p> + +<dl> + <dt>{{domxref("Window.alert()")}}</dt> + <dd>Displays an alert dialog.</dd> + <dt>{{domxref("Window.back()")}} {{Non-standard_inline}} {{obsolete_inline}}</dt> + <dd>Moves back one in the window history.</dd> + <dt>{{domxref("Window.blur()")}}</dt> + <dd>Sets focus away from the window.</dd> + <dt>{{domxref("Window.cancelAnimationFrame()")}} {{experimental_inline}}</dt> + <dd>Enables you to cancel a callback previously scheduled with {{domxref("Window.requestAnimationFrame")}}.</dd> + <dt>{{domxref("Window.cancelIdleCallback()")}} {{experimental_inline}}</dt> + <dd>Enables you to cancel a callback previously scheduled with {{domxref("Window.requestIdleCallback")}}.</dd> + <dt>{{domxref("Window.captureEvents()")}} {{Deprecated_inline}}</dt> + <dd>Registers the window to capture all events of the specified type.</dd> + <dt>{{domxref("Window.clearImmediate()")}}</dt> + <dd>Cancels the repeated execution set using <code>setImmediate</code>.</dd> + <dt>{{domxref("Window.close()")}}</dt> + <dd>Closes the current window.</dd> + <dt>{{domxref("Window.confirm()")}}</dt> + <dd>Displays a dialog with a message that the user needs to respond to.</dd> + <dt>{{domxref("Window.disableExternalCapture()")}} {{obsolete_inline(24)}}</dt> + <dd>{{todo("NeedsContents")}}</dd> + <dt>{{domxref("Window.dispatchEvent()")}}</dt> + <dd>Used to trigger an event.</dd> + <dt>{{domxref("Window.dump()")}} {{Non-standard_inline}}</dt> + <dd>Writes a message to the console.</dd> + <dt>{{domxref("Window.enableExternalCapture()")}} {{obsolete_inline(24)}}</dt> + <dd>{{todo("NeedsContents")}}</dd> + <dt>{{domxref("Window.find()")}}</dt> + <dd>Searches for a given string in a window.</dd> + <dt>{{domxref("Window.focus()")}}</dt> + <dd>Sets focus on the current window.</dd> + <dt>{{domxref("Window.forward()")}} {{Non-standard_inline}} {{obsolete_inline}}</dt> + <dd>Moves the window one document forward in the history.</dd> + <dt>{{domxref("Window.getAttention()")}} {{Non-standard_inline}} {{obsolete_inline}}</dt> + <dd>Flashes the application icon.</dd> + <dt>{{domxref("Window.getAttentionWithCycleCount()")}}</dt> + <dd>{{todo("NeedsContents")}}</dd> + <dt>{{domxref("Window.getComputedStyle()")}}</dt> + <dd>Gets computed style for the specified element. Computed style indicates the computed values of all CSS properties of the element.</dd> + <dt>{{domxref("Window.getDefaultComputedStyle()")}} {{Non-standard_inline}}</dt> + <dd>Gets default computed style for the specified element, ignoring author stylesheets.</dd> + <dt>{{domxref("Window.getSelection()")}}</dt> + <dd>Returns the selection object representing the selected item(s).</dd> + <dt>{{domxref("Window.home()")}} {{Non-standard_inline}} {{obsolete_inline}}</dt> + <dd>Returns the browser to the home page.</dd> + <dt>{{domxref("Window.matchMedia()")}} {{gecko_minversion_inline("6.0")}}</dt> + <dd>Returns a {{domxref("MediaQueryList")}} object representing the specified media query string.</dd> + <dt>{{domxref("Window.maximize()")}}</dt> + <dd>{{todo("NeedsContents")}}</dd> + <dt>{{domxref("Window.minimize()")}} (top-level XUL windows only)</dt> + <dd>Minimizes the window.</dd> + <dt>{{domxref("Window.moveBy()")}}</dt> + <dd>Moves the current window by a specified amount.</dd> + <dt>{{domxref("Window.moveTo()")}}</dt> + <dd>Moves the window to the specified coordinates.</dd> + <dt>{{domxref("Window.open()")}}</dt> + <dd>Opens a new window.</dd> + <dt>{{domxref("Window.openDialog()")}} {{Non-standard_inline}} {{obsolete_inline}}</dt> + <dd>Opens a new dialog window.</dd> + <dt>{{domxref("Window.postMessage()")}} {{Fx_minversion_inline(3)}}</dt> + <dd>Provides a secure means for one window to send a string of data to another window, which need not be within the same domain as the first.</dd> + <dt>{{domxref("Window.print()")}}</dt> + <dd>Opens the Print Dialog to print the current document.</dd> + <dt>{{domxref("Window.prompt()")}}</dt> + <dd>Returns the text entered by the user in a prompt dialog.</dd> + <dt>{{domxref("Window.releaseEvents()")}} {{Non-standard_inline}} {{Deprecated_inline}}</dt> + <dd>Releases the window from trapping events of a specific type.</dd> + <dt>{{domxref("Window.requestAnimationFrame()")}} {{gecko_minversion_inline("2.0")}}</dt> + <dd>Tells the browser that an animation is in progress, requesting that the browser schedule a repaint of the window for the next animation frame.</dd> + <dt>{{domxref("Window.requestIdleCallback()")}} {{experimental_inline}}</dt> + <dd>Enables the scheduling of tasks during a browser's idle periods.</dd> + <dt>{{domxref("Window.resizeBy()")}}</dt> + <dd>Resizes the current window by a certain amount.</dd> + <dt>{{domxref("Window.resizeTo()")}}</dt> + <dd>Dynamically resizes window.</dd> + <dt>{{domxref("Window.restore()")}} {{Non-standard_inline}} {{obsolete_inline}}</dt> + <dd>{{todo("NeedsContents")}}</dd> + <dt>{{domxref("Window.routeEvent()")}} {{obsolete_inline(24)}}</dt> + <dd>{{todo("NeedsContents")}}</dd> + <dt>{{domxref("Window.scroll()")}}</dt> + <dd>Scrolls the window to a particular place in the document.</dd> + <dt>{{domxref("Window.scrollBy()")}}</dt> + <dd>Scrolls the document in the window by the given amount.</dd> + <dt>{{domxref("Window.scrollByLines()")}} {{Non-standard_inline}}</dt> + <dd>Scrolls the document by the given number of lines.</dd> + <dt>{{domxref("Window.scrollByPages()")}} {{Non-standard_inline}}</dt> + <dd>Scrolls the current document by the specified number of pages.</dd> + <dt>{{domxref("Window.scrollTo()")}}</dt> + <dd>Scrolls to a particular set of coordinates in the document.</dd> + <dt>{{domxref("Window.setCursor()")}} {{Non-standard_inline}} (top-level XUL windows only)</dt> + <dd>Changes the cursor for the current window</dd> + <dt>{{domxref("Window.setImmediate()")}}</dt> + <dd>Executes a function after the browser has finished other heavy tasks</dd> + <dt>{{domxref("Window.setResizable()")}} {{Non-standard_inline}}</dt> + <dd>Toggles a user's ability to resize a window.</dd> + <dt>{{domxref("Window.sizeToContent()")}} {{Non-standard_inline}}</dt> + <dd>Sizes the window according to its content.</dd> + <dt>{{domxref("Window.stop()")}}</dt> + <dd>This method stops window loading.</dd> + <dt>{{domxref("Window.updateCommands()")}} {{Non-standard_inline}}</dt> + <dd>Updates the state of commands of the current chrome window (UI).</dd> +</dl> + +<h3 id="Methods_implemented_from_elsewhere">Methods implemented from elsewhere</h3> + +<dl> + <dt>{{domxref("EventTarget.addEventListener()")}}</dt> + <dd>Register an event handler to a specific event type on the window.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.atob()")}}</dt> + <dd>Decodes a string of data which has been encoded using base-64 encoding.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.btoa()")}}</dt> + <dd>Creates a base-64 encoded ASCII string from a string of binary data.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.clearInterval()")}}</dt> + <dd>Cancels the repeated execution set using {{domxref("WindowOrWorkerGlobalScope.setInterval()")}}.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.clearTimeout()")}}</dt> + <dd>Cancels the delayed execution set using {{domxref("WindowOrWorkerGlobalScope.setTimeout()")}}.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.createImageBitmap()")}}</dt> + <dd>Accepts a variety of different image sources, and returns a {{domxref("Promise")}} which resolves to an {{domxref("ImageBitmap")}}. Optionally the source is cropped to the rectangle of pixels originating at <em>(sx, sy)</em> with width sw, and height sh.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.fetch()")}}</dt> + <dd>Starts the process of fetching a resource from the network.</dd> + <dt>{{domxref("EventTarget.removeEventListener")}}</dt> + <dd>Removes an event listener from the window.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.setInterval()")}}</dt> + <dd>Schedules a function to execute every time a given number of milliseconds elapses.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.setTimeout()")}}</dt> + <dd>Schedules a function to execute in a given amount of time.</dd> +</dl> + +<h3 id="Obsolete_methods">Obsolete methods</h3> + +<dl> + <dt>{{domxref("Window.showModalDialog()")}} {{obsolete_inline}}</dt> + <dd>Displays a modal dialog. <strong>This method was removed completely in Chrome 43, and Firefox 55.</strong></dd> +</dl> + +<h2 id="事件處理器">事件處理器</h2> + +<p>These are properties of the window object that can be set to establish event handlers for the various things that can happen in the window that might be of interest.</p> + +<p><em>This interface inherits event handlers from the {{domxref("EventTarget")}} interface and implements event handlers from {{domxref("WindowEventHandlers")}}.</em></p> + +<div class="note"> +<p><strong>Note:</strong> Starting in {{Gecko("9.0")}}, you can now use the syntax <code>if ("onabort" in window)</code> to determine whether or not a given event handler property exists. This is because event handler interfaces have been updated to be proper web IDL interfaces. See <a href="/zh-TW/docs/DOM/DOM_event_handlers">DOM event handlers</a> for details.</p> +</div> + +<dl> + <dt>{{domxref("GlobalEventHandlers.onabort")}}</dt> + <dd>Called when the loading of a resource has been aborted, such as by a user canceling the load while it is still in progress</dd> + <dt>{{domxref("WindowEventHandlers.onafterprint")}}</dt> + <dd>Called when the print dialog box is closed. See {{event("afterprint")}} event.</dd> + <dt>{{domxref("WindowEventHandlers.onbeforeprint")}}</dt> + <dd>Called when the print dialog box is opened. See {{event("beforeprint")}} event.</dd> + <dt>{{domxref("Window.onbeforeinstallprompt")}}</dt> + <dd>An event handler property dispatched before a user is prompted to save a web site to a home screen on mobile.</dd> + <dt>{{domxref("WindowEventHandlers.onbeforeunload")}}</dt> + <dd>An event handler property for before-unload events on the window.</dd> + <dt>{{domxref("GlobalEventHandlers.onblur")}}</dt> + <dd>Called after the window loses focus, such as due to a popup.</dd> + <dt>{{domxref("GlobalEventHandlers.onchange")}}</dt> + <dd>An event handler property for change events on the window.</dd> + <dt>{{domxref("GlobalEventHandlers.onclick")}}</dt> + <dd>Called after the ANY mouse button is pressed & released</dd> + <dt>{{domxref("GlobalEventHandlers.ondblclick")}}</dt> + <dd>Called when a double click is made with ANY mouse button.</dd> + <dt>{{domxref("GlobalEventHandlers.onclose")}}</dt> + <dd>Called after the window is closed</dd> + <dt>{{domxref("GlobalEventHandlers.oncontextmenu")}}</dt> + <dd>Called when the RIGHT mouse button is pressed</dd> + <dt>{{domxref("Window.ondevicelight")}}</dt> + <dd>An event handler property for any ambient light levels changes</dd> + <dt>{{domxref("Window.ondevicemotion")}} {{gecko_minversion_inline("6.0")}}</dt> + <dd>Called if accelerometer detects a change (For mobile devices)</dd> + <dt>{{domxref("Window.ondeviceorientation")}} {{gecko_minversion_inline("6.0")}}</dt> + <dd>Called when the orientation is changed (For mobile devices)</dd> + <dt>{{domxref("Window.ondeviceorientationabsolute")}} {{non-standard_inline}} Chrome only</dt> + <dd>An event handler property for any device orientation changes.</dd> + <dt>{{domxref("Window.ondeviceproximity")}}</dt> + <dd>An event handler property for device proximity event</dd> + <dt>{{domxref("GlobalEventHandlers.onerror")}}</dt> + <dd>Called when a resource fails to load OR when an error occurs at runtime. See {{event("error")}} event.</dd> + <dt>{{domxref("GlobalEventHandlers.onfocus")}}</dt> + <dd>Called after the window receives or regains focus. See {{event("focus")}} events.</dd> + <dt>{{domxref("WindowEventHandlers.onhashchange")}} {{gecko_minversion_inline("1.9.2")}}</dt> + <dd>An event handler property for {{event('hashchange')}} events on the window; called when the part of the URL after the hash mark ("#") changes.</dd> + <dt>{{domxref("Window.onappinstalled")}}</dt> + <dd>Called when the page is installed as a webapp. See {{event('appinstalled')}} event.</dd> + <dt>{{domxref("Window.ongamepadconnected")}}</dt> + <dd>Represents an event handler that will run when a gamepad is connected (when the {{event('gamepadconnected')}} event fires).</dd> + <dt>{{domxref("Window.ongamepaddisconnected")}}</dt> + <dd>Represents an event handler that will run when a gamepad is disconnected (when the {{event('gamepaddisconnected')}} event fires).</dd> + <dt>{{domxref("Window.oninput")}}</dt> + <dd>Called when the value of an <input> element changes</dd> + <dt>{{domxref("GlobalEventHandlers.onkeydown")}}</dt> + <dd>Called when you begin pressing ANY key. See {{event("keydown")}} event.</dd> + <dt>{{domxref("GlobalEventHandlers.onkeypress")}}</dt> + <dd>Called when a key (except Shift, Fn, and CapsLock) is in pressed position. See {{event("keypress")}} event.</dd> + <dt>{{domxref("GlobalEventHandlers.onkeyup")}}</dt> + <dd>Called when you finish releasing ANY key. See {{event("keyup")}} event.</dd> + <dt>{{domxref("WindowEventHandlers.onlanguagechange")}}</dt> + <dd>An event handler property for {{event("languagechange")}} events on the window.</dd> + <dt>{{domxref("GlobalEventHandlers.onload")}}</dt> + <dd>Called after all resources and the DOM are fully loaded. WILL NOT get called when the page is loaded from cache, such as with back button.</dd> + <dt>{{domxref("WindowEventHandlers.onmessage")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("message")}} event is raised.</dd> + <dt>{{domxref("GlobalEventHandlers.onmousedown")}}</dt> + <dd>Called when ANY mouse button is pressed.</dd> + <dt>{{domxref("GlobalEventHandlers.onmousemove")}}</dt> + <dd>Called continously when the mouse is moved inside the window.</dd> + <dt>{{domxref("GlobalEventHandlers.onmouseout")}}</dt> + <dd>Called when the pointer leaves the window.</dd> + <dt>{{domxref("GlobalEventHandlers.onmouseover")}}</dt> + <dd>Called when the pointer enters the window</dd> + <dt>{{domxref("GlobalEventHandlers.onmouseup")}}</dt> + <dd>Called when ANY mouse button is released</dd> + <dt>{{domxref("Window.onmozbeforepaint")}} {{gecko_minversion_inline("2.0")}}</dt> + <dd>An event handler property for the <code>MozBeforePaint</code> event, which is sent before repainting the window if the event has been requested by a call to the {{domxref("Window.mozRequestAnimationFrame()")}} method.</dd> + <dt>{{domxref("WindowEventHandlers.onoffline")}}</dt> + <dd>Called when network connection is lost. See {{event("offline")}} event.</dd> + <dt>{{domxref("WindowEventHandlers.ononline")}}</dt> + <dd>Called when network connection is established. See {{event("online")}} event.</dd> + <dt>{{domxref("WindowEventHandlers.onpagehide")}}</dt> + <dd>Called when the user navigates away from the page, before the onunload event. See {{event("pagehide")}} event.</dd> + <dt>{{domxref("WindowEventHandlers.onpageshow")}}</dt> + <dd>Called after all resources and the DOM are fully loaded. See {{event("pageshow")}} event.</dd> + <dt>{{domxref("Window.onpaint")}}</dt> + <dd>An event handler property for paint events on the window.</dd> + <dt>{{domxref("WindowEventHandlers.onpopstate")}} {{gecko_minversion_inline("2.0")}}</dt> + <dd>Called when a back putton is pressed.</dd> + <dt>{{domxref("Window.onrejectionhandled")}} {{experimental_inline}}</dt> + <dd>An event handler for handled {{jsxref("Promise")}} rejection events.</dd> + <dt>{{domxref("GlobalEventHandlers.onreset")}}</dt> + <dd>Called when a form is reset</dd> + <dt>{{domxref("GlobalEventHandlers.onresize")}}</dt> + <dd>Called continuously as you are resizing the window.</dd> + <dt>{{domxref("GlobalEventHandlers.onscroll")}}</dt> + <dd>Called when the scroll bar is moved via ANY means. If the resource fully fits in the window, then this event cannot be invoked</dd> + <dt>{{domxref("GlobalEventHandlers.onwheel")}}</dt> + <dd>Called when the mouse wheel is rotated around any axis</dd> + <dt>{{domxref("GlobalEventHandlers.onselect")}}</dt> + <dd>Called after text in an input field is selected</dd> + <dt>{{domxref("GlobalEventHandlers.onselectionchange")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("selectionchange")}} event is raised.</dd> + <dt>{{domxref("WindowEventHandlers.onstorage")}}</dt> + <dd>Called when there is a change in session storage or local storage. See {{event("storage")}} event</dd> + <dt>{{domxref("GlobalEventHandlers.onsubmit")}}</dt> + <dd>Called when a form is submitted</dd> + <dt>{{domxref("WindowEventHandlers.onunhandledrejection")}} {{experimental_inline}}</dt> + <dd>An event handler for unhandled {{jsxref("Promise")}} rejection events.</dd> + <dt>{{domxref("WindowEventHandlers.onunload")}}</dt> + <dd>Called when the user navigates away from the page.</dd> + <dt>{{domxref("Window.onuserproximity")}}</dt> + <dd>An event handler property for user proximity events.</dd> + <dt>{{domxref("Window.onvrdisplayconnect")}}</dt> + <dd>Represents an event handler that will run when a compatible VR device has been connected to the computer (when the {{event("vrdisplayconnected")}} event fires).</dd> + <dt>{{domxref("Window.onvrdisplaydisconnect")}}</dt> + <dd>Represents an event handler that will run when a compatible VR device has been disconnected from the computer (when the {{event("vrdisplaydisconnected")}} event fires).</dd> + <dt>{{domxref("Window.onvrdisplayactivate")}}</dt> + <dd>Represents an event handler that will run when a display is able to be presented to (when the {{event("vrdisplayactivate")}} event fires), for example if an HMD has been moved to bring it out of standby, or woken up by being put on.</dd> + <dt>{{domxref("Window.onvrdisplaydeactivate")}}</dt> + <dd>Represents an event handler that will run when a display can no longer be presented to (when the {{event("vrdisplaydeactivate")}} event fires), for example if an HMD has gone into standby or sleep mode due to a period of inactivity.</dd> + <dt>{{domxref("Window.onvrdisplayblur")}}</dt> + <dd>Represents an event handler that will run when presentation to a display has been paused for some reason by the browser, OS, or VR hardware (when the {{event("vrdisplayblur")}} event fires) — for example, while the user is interacting with a system menu or browser, to prevent tracking or loss of experience.</dd> + <dt>{{domxref("Window.onvrdisplayfocus")}}</dt> + <dd>Represents an event handler that will run when presentation to a display has resumed after being blurred (when the {{event("vrdisplayfocus")}} event fires).</dd> + <dt>{{domxref("Window.onvrdisplaypresentchange")}}</dt> + <dd>represents an event handler that will run when the presenting state of a VR device changes — i.e. goes from presenting to not presenting, or vice versa (when the {{event("vrdisplaypresentchange")}} event fires).</dd> +</dl> + +<h2 id="建構式">建構式</h2> + +<p>See also the <a href="/zh-TW/docs/DOM/DOM_Reference" title="/zh-TW/docs/DOM/DOM_Reference">DOM Interfaces</a>.</p> + +<dl> + <dt>{{domxref("DOMParser")}}</dt> + <dd><code>DOMParser</code> can parse XML or HTML source stored in a string into a DOM <a href="https://developer.mozilla.org/zh-TW/docs/DOM/document" title="document">Document</a>. <code>DOMParser</code> is specified in <a href="https://w3c.github.io/DOM-Parsing/" title="http://html5.org/specs/dom-parsing.html">DOM Parsing and Serialization</a>.</dd> + <dt>{{domxref("Window.GeckoActiveXObject")}}</dt> + <dd>{{todo("NeedsContents")}}</dd> + <dt>{{domxref("Image")}}</dt> + <dd>Used for creating an {{domxref("HTMLImageElement")}}.</dd> + <dt>{{domxref("Option")}}</dt> + <dd>Used for creating an {{domxref("HTMLOptionElement")}}</dd> + <dt>{{domxref("Window.QueryInterface")}}</dt> + <dd>{{todo("NeedsContents")}}</dd> + <dt>{{domxref("Window.XMLSerializer")}}</dt> + <dd>{{todo("NeedsContents")}}</dd> + <dt>{{domxref("Worker")}}</dt> + <dd>Used for creating a <a href="/zh-TW/docs/DOM/Using_web_workers">Web worker</a></dd> + <dt>{{domxref("Window.XPCNativeWrapper")}}</dt> + <dd>{{todo("NeedsContents")}}</dd> + <dt>{{domxref("Window.XPCSafeJSObjectWrapper")}}</dt> + <dd>{{todo("NeedsContents")}}</dd> +</dl> + +<h2 id="相關介面">相關介面</h2> + +<p>請參閱 {{domxref("Document_Object_Model", "DOM Reference")}}</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/zh-TW/docs/Working_with_windows_in_chrome_code">Working with windows in chrome code</a></li> +</ul> diff --git a/files/zh-tw/web/api/window/localstorage/index.html b/files/zh-tw/web/api/window/localstorage/index.html new file mode 100644 index 0000000000..1733a325bd --- /dev/null +++ b/files/zh-tw/web/api/window/localstorage/index.html @@ -0,0 +1,82 @@ +--- +title: Window.localStorage +slug: Web/API/Window/localStorage +translation_of: Web/API/Window/localStorage +--- +<p>{{APIRef("Web Storage API")}}</p> + +<p><span class="seoSummary"><strong><code>localStorage</code></strong> 為一唯讀屬性, 此屬性允許您存取目前文件({{DOMxRef("Document")}})隸屬網域來源的 {{DOMxRef("Storage")}} 物件; 與 sessionStorage 不同的是其儲存資料的可存取範圍為跨瀏覽頁狀態(Browser Sessions).</span> <code>localStorage</code> 的應用與 {{DOMxRef("Window.sessionStorage", "sessionStorage")}} 相似, 除了 <code>localStorage</code> 的儲存資料並無到期的限制, 而 <code>sessionStorage</code> 的儲存資料於目前瀏覽頁狀態結束的同時將一併被清除 — 也就是目前瀏覽器頁面被關閉的同時.</p> + +<p>值得注意的是不論 <code>localStorage</code> 或者 <code>sessionStorage</code> <strong>皆為專屬於目前瀏覽器頁面的通訊協定(Protocol)</strong>.</p> + +<p>鍵值名稱和值皆為<strong>字串型式</strong>(請留意, 當其為物件, 整數等將自動轉換為字串型式).</p> + +<h2 id="Syntax">Syntax</h2> + +<pre class="syntaxbox"><em>myStorage</em> = <em>window</em>.localStorage;</pre> + +<h3 id="Value">Value</h3> + +<p>{{DOMxRef("Storage")}} 物件 which can be used to access the current origin's local storage space.</p> + +<h3 id="Exceptions">Exceptions</h3> + +<dl> + <dt><code>SecurityError</code></dt> + <dd>The request violates a policy decision, or the origin is not <a href="/en-US/docs/Web/Security/Same-origin_policy#Definition_of_an_origin">a valid scheme/host/port tuple</a> (this can happen if the origin uses the <code>file:</code> or <code>data:</code> scheme, for example). 舉例來說，使用者 may have their browser configured to deny permission to persist data for the specified origin.</dd> +</dl> + +<h2 id="Example">Example</h2> + +<p>下列的程式碼片段讀取了目前域名內的 local {{DOMxRef("Storage")}} 物件 ，並用{{DOMxRef("Storage.setItem()")}}，增加一個資料物件 item 到其中</p> + +<pre class="brush: js">localStorage.setItem('myCat', 'Tom');</pre> + +<p>讀取 <code>localStorage</code> 內物件的語法如下：</p> + +<pre class="brush: js">var cat = localStorage.getItem('myCat');</pre> + +<p>移除 <code>localStorage</code> 內物件的語法如下：</p> + +<pre class="brush: js">localStorage.removeItem('myCat');</pre> + +<p>刪除 <code>localStorage</code> 內所有物件的語法如下：</p> + +<pre class="brush: js">// Clear all items +localStorage.clear(); +</pre> + +<div class="note"> +<p><strong>Note</strong>: Please refer to the <a href="/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API">Using the Web Storage API</a> article for a full example.</p> +</div> + +<h2 id="Specifications">Specifications</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("HTML WHATWG", "webstorage.html#dom-localstorage", "localStorage")}}</td> + <td>{{Spec2("HTML WHATWG")}}</td> + <td></td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + + + +<p>{{Compat("api.Window.localStorage")}}</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API">Using the Web Storage API</a></li> + <li><a href="/en-US/docs/Web/API/Web_Storage_API/Local_storage">Local storage with Window.localStorage</a></li> + <li><span>{{DOMxRef("Window.sessionStorage")}}</span></li> +</ul> diff --git a/files/zh-tw/web/api/window/location/index.html b/files/zh-tw/web/api/window/location/index.html new file mode 100644 index 0000000000..a887f88ee0 --- /dev/null +++ b/files/zh-tw/web/api/window/location/index.html @@ -0,0 +1,373 @@ +--- +title: window.location +slug: Web/API/Window/location +translation_of: Web/API/Window/location +--- +<p>{{ ApiRef() }}</p> +<h3 id="Summary" name="Summary">Summary</h3> +<p>Returns a <a href="#Location_object"> <code>Location</code> object</a>, which contains information about the URL of the document and provides methods for changing that URL. You can also assign to this property to load another URL.</p> +<h3 id="Syntax" name="Syntax">語法</h3> +<pre class="eval">var <em>locationObj</em> = window.location; +window.location = <em>newLocation</em>; +</pre> +<p>where</p> +<ul> + <li><em>locationObj</em> is an object of type <code>Location</code>, providing information about the current URL and methods to change it. Its properties and methods are described below.</li> + <li><em>newLocation</em> is a <code>Location</code> object or a string, specifying the URL to navigate to.</li> +</ul> +<h3 id="Location_object" name="Location_object"><code>Location</code> object</h3> +<p>This section describes the properties and methods of the location object.</p> +<h4 id="Use_as_a_string" name="Use_as_a_string">Use as a string</h4> +<p><code>Location</code> objects have a <code>toString</code> method returning the current URL. You can also assign a string to <code>window.location</code>. This means that you can work with <code>window.location</code> as if it were a string in most cases. Sometimes, for example when you need to call a <a href="/En/Core_JavaScript_1.5_Reference/Global_Objects/String" title="en/Core_JavaScript_1.5_Reference/Global_Objects/String">String</a> method on it, you have to explicitly call <code>toString</code>:</p> +<pre class="brush: js">alert(window.location.toString().charAt(17)); +</pre> +<h4 id="Properties" name="Properties">Properties</h4> +<p>All of the following properties are strings. You can read them to get information about the current URL or set them to navigate to another URL.</p> +<p>The "Example" column contains the values of the properties of the following URL:</p> +<ul> + <li><span class="nowiki">http://[www.example.com]:80/search?q=devmo#test</span></li> +</ul> +<table class="fullwidth-table"> + <tbody> + <tr> + <th>Property</th> + <th>Description</th> + <th>Example</th> + </tr> + <tr> + <td><code>hash</code></td> + <td>the part of the URL that follows the # symbol, including the # symbol.<br> + You can listen for the <a href="/en-US/docs/Mozilla_event_reference/hashchange">hashchange event</a> to get notified of changes to the hash in supporting browsers.</td> + <td>#test</td> + </tr> + <tr> + <td><code>host</code></td> + <td>the host name and port number.</td> + <td>[www.example.com]:80</td> + </tr> + <tr> + <td><code>hostname</code></td> + <td>the host name (without the port number or square brackets).</td> + <td>www.example.com</td> + </tr> + <tr> + <td><code>href</code></td> + <td>the entire URL.</td> + <td><span class="nowiki">http://[www.example.com]:80/search?q=devmo#test</span></td> + </tr> + <tr> + <td><code>pathname</code></td> + <td>the path (relative to the host).</td> + <td>/search</td> + </tr> + <tr> + <td><code>port</code></td> + <td>the port number of the URL.</td> + <td>80</td> + </tr> + <tr> + <td><code>protocol</code></td> + <td>the protocol of the URL.</td> + <td>http:</td> + </tr> + <tr> + <td><code>search</code></td> + <td>the part of the URL that follows the ? symbol, including the ? symbol.</td> + <td>?q=devmo</td> + </tr> + </tbody> +</table> +<p>If the hash part of the URL contains encoded characters (see <a href="/en/JavaScript/Reference/Global_Objects/encodeURIComponent" title="en/Core_JavaScript_1.5_Reference/Global_Functions/encodeURIComponent">Core_JavaScript_1.5_Reference:Global_Functions:encodeURIComponent</a>), <code>hash</code> returns the decoded URL part. This is a <a class="link-https" href="https://bugzilla.mozilla.org/show_bug.cgi?id=483304" title="https://bugzilla.mozilla.org/show_bug.cgi?id=483304">bug</a> in Firefox. <code>href</code>, <code>search</code> and <code>pathname</code> return the correct, encoded URL parts. For example:</p> +<ul> + <li><span class="nowiki">http://www.example.com/search?q=Fire%20fox#Fire%20fox</span></li> +</ul> +<p>results in:</p> +<ul> + <li><span class="nowiki">hash=#Fire fox</span></li> + <li><span class="nowiki">search=?q=Fire%20fox</span></li> +</ul> +<h4 id="Methods" name="Methods">Methods</h4> +<table class="fullwidth-table"> + <tbody> + <tr> + <th>Method</th> + <th>Description</th> + </tr> + <tr> + <td><code id="assign">assign(url)</code></td> + <td>Load the document at the provided URL.</td> + </tr> + <tr> + <td><code id="reload">reload(forceget)</code></td> + <td>Reload the document from the current URL. <code>forceget</code> is a boolean, which, when it is <code>true</code>, causes the page to always be reloaded from the server. If it is <code>false</code> or not specified, the browser may reload the page from its cache.</td> + </tr> + <tr> + <td><code id="replace">replace(url)</code></td> + <td>Replace the current document with the one at the provided URL. The difference from the <code>assign()</code> method is that after using <code>replace()</code> the current page will not be saved in session history, meaning the user won't be able to use the Back button to navigate to it.</td> + </tr> + <tr> + <td><code id="toString">toString()</code></td> + <td>Returns the string representation of the <code>Location</code> object's URL. See the <a href="/en/JavaScript/Reference/Global_Objects/Object/toString" title="en/Core_JavaScript_1.5_Reference/Global_Objects/Object/toString">JavaScript reference</a> for details.</td> + </tr> + </tbody> +</table> +<h3 id="Example" name="Example">Examples</h3> +<p>Whenever a property of the location object is modified, a document will be loaded using the URL as if <code>window.location.assign()</code> had been called with the modified URL.</p> +<h5 id="Replace_the_current_document_with_the_one_at_the_given_URL">Replace the current document with the one at the given URL:</h5> +<pre class="brush: js">function goMoz() { + window.location = "http://www.mozilla.org"; +} + +// in html: <button onclick="goMoz();">Mozilla</button> + +</pre> +<div class="note"> + <strong>Note:</strong> The example above works in situations where <code>window.location.hash</code> does not need to be retained. However, in Gecko-based browsers, setting <code>window.location.pathname</code> in this manner will erase any information in <code>window.location.hash</code>, whereas in WebKit (and possibly other browsers), setting the pathname will not alter the the hash. If you need to change pathname but keep the hash as is, use the <code>replace()</code> method instead, which should work consistently across browsers.</div> +<p><br> + Consider the following example, which will reload the page by using the <code>replace()</code> method to insert the value of <code>window.location.pathname</code> into the hash (similar to Twitter's reload of <a class="external" href="http://twitter.com/username" rel="freelink">http://twitter.com/username</a> to <a class="external" href="http://twitter.com/#!/username" rel="freelink">http://twitter.com/#!/username</a>):</p> +<pre class="brush: js">function reloadPageWithHash() { + var initialPage = window.location.pathname; + window.location.replace('http://example.com/#' + initialPage); +} +</pre> +<h5 id="Display_the_properties_of_the_current_URL_in_an_alert_dialog">Display the properties of the current URL in an alert dialog:</h5> +<pre class="brush: js">function showLoc() { + var oLocation = window.location, aLog = ["Property (Typeof): Value", "window.location (" + (typeof oLocation) + "): " + oLocation ]; + for (var sProp in oLocation){ + aLog.push(sProp + " (" + (typeof oLocation[sProp]) + "): " + (oLocation[sProp] || "n/a")); + } + alert(aLog.join("\n")); +} + +// in html: <button onclick="showLoc();">Show location properties</button> +</pre> +<h5 id="Send_a_string_of_data_to_the_server_by_modifying_the_search_property">Send a string of data to the server by modifying the <code>search</code> property:</h5> +<pre class="brush: js">function sendData (sData) { + window.location.search = sData; +} + +// in html: <button onclick="sendData('Some data');">Send data</button> + +</pre> +<p>The current URL with "?Some%20data" appended is sent to the server (if no action is taken by the server, the current document is reloaded with the modified search string).</p> +<h5 id="Get_the_value_of_a_single_window.location.search_key">Get the value of a single <code>window.location.search</code> key:</h5> +<pre class="brush: js">function loadPageVar (sVar) { + return unescape(window.location.search.replace(new RegExp("^(?:.*[&\\?]" + escape(sVar).replace(/[\.\+\*]/g, "\\$&") + "(?:\\=([^&]*))?)?.*$", "i"), "$1")); +} + +alert(loadPageVar("name")); +</pre> +<h5 id="Nestle_the_variables_obtained_through_the_window.location.search_string_in_an_object_named_oGetVars">Nestle the variables obtained through the <code>window.location.search</code> string in an object named <code>oGetVars</code>:</h5> +<pre class="brush: js">var oGetVars = {}; + +if (window.location.search.length > 1) { + for (var aItKey, nKeyId = 0, aCouples = window.location.search.substr(1).split("&"); nKeyId < aCouples.length; nKeyId++) { + aItKey = aCouples[nKeyId].split("="); + oGetVars[unescape(aItKey[0])] = aItKey.length > 1 ? unescape(aItKey[1]) : ""; + } +} + +// alert(oGetVars.yourVar); +</pre> +<p>…the same thing obtained by an anonymous constructor – useful for a global variable declaration:</p> +<pre class="brush: js">var oGetVars = new (function (sSearch) { + if (sSearch.length > 1) { + for (var aItKey, nKeyId = 0, aCouples = sSearch.substr(1).split("&"); nKeyId < aCouples.length; nKeyId++) { + aItKey = aCouples[nKeyId].split("="); + this[unescape(aItKey[0])] = aItKey.length > 1 ? unescape(aItKey[1]) : ""; + } + } +})(window.location.search); + +// alert(oGetVars.yourVar); +</pre> +<h5 id="Nestle_the_variables_obtained_through_the_window.location.search_string_in_an_object_named_oGetVars_also_attempting_to_recognize_their_typeof">Nestle the variables obtained through the <code>window.location.search</code> string in an object named <code>oGetVars</code>, also attempting to recognize their <code><a href="/en/JavaScript/Reference/Operators/typeof" title="en/JavaScript/Reference/Operators/typeof">typeof</a></code>:</h5> +<pre class="brush: js">var oGetVars = {}; + +function buildValue(sValue) { + if (/^\s*$/.test(sValue)) { return null; } + if (/^(true|false)$/i.test(sValue)) { return sValue.toLowerCase() === "true"; } + if (isFinite(sValue)) { return parseFloat(sValue); } + if (isFinite(Date.parse(sValue))) { return new Date(sValue); } + return sValue; +} + +if (window.location.search.length > 1) { + for (var aItKey, nKeyId = 0, aCouples = window.location.search.substr(1).split("&"); nKeyId < aCouples.length; nKeyId++) { + aItKey = aCouples[nKeyId].split("="); + oGetVars[unescape(aItKey[0])] = aItKey.length > 1 ? buildValue(unescape(aItKey[1])) : null; + } +} + +// alert(oGetVars.yourVar); +</pre> +<p>…the same thing obtained by an anonymous constructor – useful for a global variable declaration:</p> +<pre class="brush: js">var oGetVars = new (function (sSearch) { + var rNull = /^\s*$/, rBool = /^(true|false)$/i; + function buildValue(sValue) { + if (rNull.test(sValue)) { return null; } + if (rBool.test(sValue)) { return sValue.toLowerCase() === "true"; } + if (isFinite(sValue)) { return parseFloat(sValue); } + if (isFinite(Date.parse(sValue))) { return new Date(sValue); } + return sValue; + } + if (sSearch.length > 1) { + for (var aItKey, nKeyId = 0, aCouples = sSearch.substr(1).split("&"); nKeyId < aCouples.length; nKeyId++) { + aItKey = aCouples[nKeyId].split("="); + this[unescape(aItKey[0])] = aItKey.length > 1 ? buildValue(unescape(aItKey[1])) : null; + } + } +})(window.location.search); + +// alert(oGetVars.yourVar); +</pre> +<h5 id="Using_bookmars_without_changing_the_window.location.hash_property">Using bookmars without changing the <code>window.location.hash</code> property:</h5> +<pre class="brush: html"><!doctype html> +<html> +<head> +<meta content="text/html; charset=UTF-8" http-equiv="Content-Type" /> +<title>MDN Example</title> +<script type="text/javascript"> +function showNode (oNode) { + var nLeft = 0, nTop = 0; + for (var oItNode = oNode; oItNode; nLeft += oItNode.offsetLeft, nTop += oItNode.offsetTop, oItNode = oItNode.offsetParent); + document.documentElement.scrollTop = nTop; + document.documentElement.scrollLeft = nLeft; +} + +function showBookmark (sBookmark, bUseHash) { + if (arguments.length === 1 || bUseHash) { window.location.hash = sBookmark; return; } + var oBookmark = document.querySelector(sBookmark); + if (oBookmark) { showNode(oBookmark); } +} +</script> +<style type="text/css"> +span.intLink { + cursor: pointer; + color: #0000ff; + text-decoration: underline; +} +</style> +</head> + +<body> +<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam ultrices dolor ac dolor imperdiet ullamcorper. Suspendisse quam libero, luctus auctor mollis sed, malesuada condimentum magna. Quisque in ante tellus, in placerat est. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Donec a mi magna, quis mattis dolor. Etiam sit amet ligula quis urna auctor imperdiet nec faucibus ante. Mauris vel consectetur dolor. Nunc eget elit eget velit pulvinar fringilla consectetur aliquam purus. Curabitur convallis, justo posuere porta egestas, velit erat ornare tortor, non viverra justo diam eget arcu. Phasellus adipiscing fermentum nibh ac commodo. Nam turpis nunc, suscipit a hendrerit vitae, volutpat non ipsum.</p> +<p>Duis lobortis sapien quis nisl luctus porttitor. In tempor semper libero, eu tincidunt dolor eleifend sit amet. Ut nec velit in dolor tincidunt rhoncus non non diam. Morbi auctor ornare orci, non euismod felis gravida nec. Curabitur elementum nisi a eros rutrum nec blandit diam placerat. Aenean tincidunt risus ut nisi consectetur cursus. Ut vitae quam elit. Donec dignissim est in quam tempor consequat. Aliquam aliquam diam non felis convallis suscipit. Nulla facilisi. Donec lacus risus, dignissim et fringilla et, egestas vel eros. Duis malesuada accumsan dui, at fringilla mauris bibendum quis. Cras adipiscing ultricies fermentum. Praesent bibendum condimentum feugiat.</p> +<p id="myBookmark1">[&nbsp;<span class="intLink" onclick="showBookmark('#myBookmark2');">Go to bookmark #2</span>&nbsp;]</p> +<p>Vivamus blandit massa ut metus mattis in fringilla lectus imperdiet. Proin ac ante a felis ornare vehicula. Fusce pellentesque lacus vitae eros convallis ut mollis magna pellentesque. Pellentesque placerat enim at lacus ultricies vitae facilisis nisi fringilla. In tincidunt tincidunt tincidunt. Nulla vitae tempor nisl. Etiam congue, elit vitae egestas mollis, ipsum nisi malesuada turpis, a volutpat arcu arcu id risus.</p> +<p>Nam faucibus, ligula eu fringilla pulvinar, lectus tellus iaculis nunc, vitae scelerisque metus leo non metus. Proin mattis lobortis lobortis. Quisque accumsan faucibus erat, vel varius tortor ultricies ac. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nec libero nunc. Nullam tortor nunc, elementum a consectetur et, ultrices eu orci. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque a nisl eu sem vehicula egestas.</p> +<p>Aenean viverra varius mauris, sed elementum lacus interdum non. Phasellus sit amet lectus vitae eros egestas pellentesque fermentum eget magna. Quisque mauris nisl, gravida vitae placerat et, condimentum id metus. Nulla eu est dictum dolor pulvinar volutpat. Pellentesque vitae sollicitudin nunc. Donec neque magna, lobortis id egestas nec, sodales quis lectus. Fusce cursus sollicitudin porta. Suspendisse ut tortor in mauris tincidunt rhoncus. Maecenas tincidunt fermentum facilisis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p> +<p>Suspendisse turpis nisl, consectetur in lacinia ut, ornare vel mi. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin non lectus eu turpis vulputate cursus. Mauris interdum tincidunt erat id pharetra. Nullam in libero elit, sed consequat lectus. Morbi odio nisi, porta vitae molestie ut, gravida ut nunc. Ut non est dui, id ullamcorper orci. Praesent vel elementum felis. Maecenas ornare, dui quis auctor hendrerit, turpis sem ullamcorper odio, in auctor magna metus quis leo. Morbi at odio ante.</p> +<p>Curabitur est ipsum, porta ac viverra faucibus, eleifend sed eros. In sit amet vehicula tortor. Vestibulum viverra pellentesque erat a elementum. Integer commodo ultricies lorem, eget tincidunt risus viverra et. In enim turpis, porttitor ac ornare et, suscipit sit amet nisl. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Pellentesque vel ultrices nibh. Sed commodo aliquam aliquam. Nulla euismod, odio ut eleifend mollis, nisi dui gravida nibh, vitae laoreet turpis purus id ipsum. Donec convallis, velit non scelerisque bibendum, diam nulla auctor nunc, vel dictum risus ipsum sit amet est. Praesent ut nibh sit amet nibh congue pulvinar. Suspendisse dictum porttitor tempor.</p> +<p>Vestibulum dignissim erat vitae lectus auctor ac bibendum eros semper. Integer aliquet, leo non ornare faucibus, risus arcu tristique dolor, a aliquet massa mauris quis arcu. In porttitor, lectus ac semper egestas, ligula magna laoreet libero, eu commodo mauris odio id ante. In hac habitasse platea dictumst. In pretium erat diam, nec consequat eros. Praesent augue mi, consequat sed porttitor at, volutpat vitae eros. Sed pretium pharetra dapibus. Donec auctor interdum erat, lacinia molestie nibh commodo ut. Maecenas vestibulum vulputate felis, ut ullamcorper arcu faucibus in. Curabitur id arcu est. In semper mollis lorem at pellentesque. Sed lectus nisl, vestibulum id scelerisque eu, feugiat et tortor. Pellentesque porttitor facilisis ultricies.</p> +<p id="myBookmark2">[&nbsp;<span class="intLink" onclick="showBookmark('#myBookmark1');">Go to bookmark #1</span> | <span class="intLink" onclick="showBookmark('#myBookmark1', false);">Go to bookmark #1 without using location.hash</span> | <span class="intLink" onclick="showBookmark('#myBookmark3');">Go to bookmark #3</span>&nbsp;]</p> +<p>Phasellus tempus fringilla nunc, eget sagittis orci molestie vel. Nulla sollicitudin diam non quam iaculis ac porta justo venenatis. Quisque tellus urna, molestie vitae egestas sit amet, suscipit sed sem. Quisque nec lorem eu velit faucibus tristique ut ut dolor. Cras eu tortor ut libero placerat venenatis ut ut massa. Sed quis libero augue, et consequat libero. Morbi rutrum augue sed turpis elementum sed luctus nisl molestie. Aenean vitae purus risus, a semper nisl. Pellentesque malesuada, est id sagittis consequat, libero mauris tincidunt tellus, eu sagittis arcu purus rutrum eros. Quisque eget eleifend mi. Duis pharetra mi ac eros mattis lacinia rutrum ipsum varius.</p> +<p>Fusce cursus pulvinar aliquam. Duis justo enim, ornare vitae elementum sed, porta a quam. Aliquam eu enim eu libero mollis tempus. Morbi ornare aliquam posuere. Proin faucibus luctus libero, sed ultrices lorem sagittis et. Vestibulum malesuada, ante nec molestie vehicula, quam diam mollis ipsum, rhoncus posuere mauris lectus in eros. Nullam feugiat ultrices augue, ac sodales sem mollis in.</p> +<p id="myBookmark3"><em>Here is the bookmark #3</em></p> +<p>Proin vitae sem non lorem pellentesque molestie. Nam tempus massa et turpis placerat sit amet sollicitudin orci sodales. Pellentesque enim enim, sagittis a lobortis ut, tempus sed arcu. Aliquam augue turpis, varius vel bibendum ut, aliquam at diam. Nam lobortis, dui eu hendrerit pellentesque, sem neque porttitor erat, non dapibus velit lectus in metus. Vestibulum sit amet felis enim. In quis est vitae nunc malesuada consequat nec nec sapien. Suspendisse aliquam massa placerat dui lacinia luctus sed vitae risus. Fusce tempus, neque id ultrices volutpat, mi urna auctor arcu, viverra semper libero sem vel enim. Mauris dictum, elit non placerat malesuada, libero elit euismod nibh, nec posuere massa arcu eu risus. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer urna velit, dapibus eget varius feugiat, pellentesque sit amet ligula. Maecenas nulla nisl, facilisis eu egestas scelerisque, mollis eget metus. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Morbi sed congue mi.</p> +<p>Fusce metus velit, pharetra at vestibulum nec, facilisis porttitor mi. Curabitur ligula sapien, fermentum vel porttitor id, rutrum sit amet magna. Sed sit amet sollicitudin turpis. Aenean luctus rhoncus dolor, et pulvinar ante egestas et. Donec ac massa orci, quis dapibus augue. Vivamus consectetur auctor pellentesque. Praesent vestibulum tincidunt ante sed consectetur. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Fusce purus metus, imperdiet vitae iaculis convallis, bibendum vitae turpis.</p> +<p>Fusce aliquet molestie dolor, in ornare dui sodales nec. In molestie sollicitudin felis a porta. Mauris nec orci sit amet orci blandit tristique congue nec nunc. Praesent et tellus sollicitudin mauris accumsan fringilla. Morbi sodales, justo eu sollicitudin lacinia, lectus sapien ullamcorper eros, quis molestie urna elit bibendum risus. Proin eget tincidunt quam. Nam luctus commodo mauris, eu posuere nunc luctus non. Nulla facilisi. Vivamus eget leo rhoncus quam accumsan fringilla. Aliquam sit amet lorem est. Nullam vel tellus nibh, id imperdiet orci. Integer egestas leo eu turpis blandit scelerisque.</p> +<p>Etiam in blandit tellus. Integer sed varius quam. Vestibulum dapibus mi gravida arcu viverra blandit. Praesent tristique augue id sem adipiscing pellentesque. Sed sollicitudin, leo sed interdum elementum, nisi ante condimentum leo, eget ornare libero diam semper quam. Vivamus augue urna, porta eget ultrices et, dapibus ut ligula. Ut laoreet consequat faucibus. Praesent at lectus ut lectus malesuada mollis. Nam interdum adipiscing eros, nec sodales mi porta nec. Proin et quam vitae sem interdum aliquet. Proin vel odio at lacus vehicula aliquet.</p> +<p>Etiam placerat dui ut sem ornare vel vestibulum augue mattis. Sed semper malesuada mi, eu bibendum lacus lobortis nec. Etiam fringilla elementum risus, eget consequat urna laoreet nec. Etiam mollis quam non sem convallis vel consectetur lectus ullamcorper. Aenean mattis lacus quis ligula mattis eget vestibulum diam hendrerit. In non placerat mauris. Praesent faucibus nunc quis eros sagittis viverra. In hac habitasse platea dictumst. Suspendisse eget nisl erat, ac molestie massa. Praesent mollis vestibulum tincidunt. Fusce suscipit laoreet malesuada. Aliquam erat volutpat. Aliquam dictum elementum rhoncus. Praesent in est massa, pulvinar sodales nunc. Pellentesque gravida euismod mi ac convallis.</p> +<p>Mauris vel odio vel nulla facilisis lacinia. Aliquam ultrices est at leo blandit tincidunt. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Suspendisse porttitor adipiscing facilisis. Duis cursus quam iaculis augue interdum porttitor. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Duis vulputate magna ac metus pretium condimentum. In tempus, est eget vestibulum blandit, velit massa dignissim nisl, ut scelerisque lorem neque vel velit. Maecenas fermentum commodo viverra. Curabitur a nibh non velit aliquam cursus. Integer semper condimentum tortor a pellentesque. Pellentesque semper, nisl id porttitor vehicula, sem dui feugiat lacus, vitae consequat augue urna vel odio.</p> +<p>Vestibulum id neque nec turpis iaculis pulvinar et a massa. Vestibulum sed nibh vitae arcu eleifend egestas. Mauris fermentum ultrices blandit. Suspendisse vitae lorem libero. Aenean et pellentesque tellus. Morbi quis neque orci, eu dignissim dui. Fusce sollicitudin mauris ac arcu vestibulum imperdiet. Proin ultricies nisl sit amet enim imperdiet eu ornare dui tempus. Maecenas lobortis nisi a tortor vestibulum vel eleifend tellus vestibulum. Donec metus sapien, hendrerit a fermentum id, dictum quis libero.</p> +<p>Pellentesque a lorem nulla, in tempor justo. Duis odio nisl, dignissim sed consequat sit amet, hendrerit ac neque. Nunc ac augue nec massa tempor rhoncus. Nam feugiat, tellus a varius euismod, justo nisl faucibus velit, ut vulputate justo massa eu nibh. Sed bibendum urna quis magna facilisis in accumsan dolor malesuada. Morbi sit amet nunc risus, in faucibus sem. Nullam sollicitudin magna sed sem mollis id commodo libero condimentum. Duis eu massa et lacus semper molestie ut adipiscing sem.</p> +<p>Sed id nulla mi, eget suscipit eros. Aliquam tempus molestie rutrum. In quis varius elit. Nullam dignissim neque nec velit vulputate porttitor. Mauris ac ligula sit amet elit fermentum rhoncus. In tellus urna, pulvinar quis condimentum ut, porta nec justo. In hac habitasse platea dictumst. Proin volutpat elit id quam molestie ac commodo lacus sagittis. Quisque placerat, augue tempor placerat pulvinar, nisi nisi venenatis urna, eget convallis eros velit quis magna. Suspendisse volutpat iaculis quam, ut tristique lacus luctus quis.</p> +<p>Nullam commodo suscipit lacus non aliquet. Phasellus ac nisl lorem, sed facilisis ligula. Nam cursus lobortis placerat. Sed dui nisi, elementum eu sodales ac, placerat sit amet mauris. Pellentesque dapibus tellus ut ipsum aliquam eu auctor dui vehicula. Quisque ultrices laoreet erat, at ultrices tortor sodales non. Sed venenatis luctus magna, ultricies ultricies nunc fringilla eget. Praesent scelerisque urna vitae nibh tristique varius consequat neque luctus. Integer ornare, erat a porta tempus, velit justo fermentum elit, a fermentum metus nisi eu ipsum. Vivamus eget augue vel dui viverra adipiscing congue ut massa. Praesent vitae eros erat, pulvinar laoreet magna. Maecenas vestibulum mollis nunc in posuere. Pellentesque sit amet metus a turpis lobortis tempor eu vel tortor. Cras sodales eleifend interdum.</p> +</body> +</html> +</pre> +<div class="note"> + <strong>Note:</strong> The function <code>showNode</code> is also an example of the use of the <code><a href="/en/JavaScript/Reference/Statements/for" title="en/JavaScript/Reference/Statements/for">for</a></code> cycle without a <code>statement</code> section. In this case <strong>a semicolon is always put immediately after the declaration of the cycle</strong>.</div> +<p>…the same thing but with a dynamic page scroll:</p> +<pre class="brush: js">var showBookmark = (function () { + var _useHash, _scrollX, _scrollY, _nodeX, _nodeY, _itFrame, _scrollId = -1, _bookMark, + /* + * nDuration: the duration in milliseconds of each frame + * nFrames: number of frames for each scroll + */ + nDuration = 200, nFrames = 10; + + function _next () { + if (_itFrame > nFrames) { clearInterval(_scrollId); _scrollId = -1; return; } + _isBot = true; + document.documentElement.scrollTop = Math.round(_scrollY + (_nodeY - _scrollY) * _itFrame / nFrames); + document.documentElement.scrollLeft = Math.round(_scrollX + (_nodeX - _scrollX) * _itFrame / nFrames); + if (_useHash && _itFrame === nFrames) { location.hash = _bookMark; } + _itFrame++; + } + + function _chkOwner () { + if (_isBot) { _isBot = false; return; } + if (_scrollId > -1) { clearInterval(_scrollId); _scrollId = -1; } + } + + if (window.addEventListener) { window.addEventListener("scroll", _chkOwner, false); } + else if (window.attachEvent) { window.attachEvent("onscroll", _chkOwner); } + + return function (sBookmark, bUseHash) { + _scrollY = document.documentElement.scrollTop; + _scrollX = document.documentElement.scrollLeft; + _bookMark = sBookmark; + _useHash = arguments.length === 1 || bUseHash; + for ( + var nLeft = 0, nTop = 0, oNode = document.querySelector(sBookmark); + oNode; + nLeft += oNode.offsetLeft, nTop += oNode.offsetTop, oNode = oNode.offsetParent + ); + _nodeX = nLeft, _nodeY = nTop, _itFrame = 1; + if (_scrollId === -1) { _scrollId = setInterval(_next, Math.round(nDuration / nFrames)); } + }; +})(); +</pre> +<h3 id="See_also">See also</h3> +<p><a href="/en/DOM/Manipulating_the_browser_history" title="en/DOM/Manipulating the browser history">Manipulating the browser history</a></p> +<h3 id="Browser_Compatibility" name="Browser_Compatibility">Browser compatibility</h3> +<p>{{ CompatibilityTable() }}</p> +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + </tbody> + </table> +</div> +<div id="compat-mobile"> + <table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + </tbody> + </table> +</div> +<h3 id="Specification" name="Specification">Specification</h3> +<p>HTML Specification: <var>window</var> . <code title="dom-location"><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/history.html#dom-location">location</a></code></p> +<p>{{ languages( { "fr": "fr/DOM/window.location", "ja": "ja/DOM/window.location" } ) }}</p> diff --git a/files/zh-tw/web/api/window/navigator/index.html b/files/zh-tw/web/api/window/navigator/index.html new file mode 100644 index 0000000000..f729c810a9 --- /dev/null +++ b/files/zh-tw/web/api/window/navigator/index.html @@ -0,0 +1,58 @@ +--- +title: Window.navigator +slug: Web/API/Window/navigator +translation_of: Web/API/Window/navigator +--- +<div>{{APIRef}}</div> + +<p>The <code>Window.navigator</code> read-only property returns a reference to the {{domxref("Navigator")}} object, which can be queried for information about the application running the script.</p> + +<h2 id="Example" name="Example">語法</h2> + +<pre class="syntaxbox"><em>navigatorObject<code> = window.navigator</code></em></pre> + +<h2 id="Specification" name="Specification">範例</h2> + +<h3 id="Example_1_Browser_detect_and_return_a_string">Example #1: Browser detect and return a string</h3> + +<pre class="brush: js">var sBrowser, sUsrAg = navigator.userAgent; + +if(sUsrAg.indexOf("Chrome") > -1) { + sBrowser = "Google Chrome"; +} else if (sUsrAg.indexOf("Safari") > -1) { + sBrowser = "Apple Safari"; +} else if (sUsrAg.indexOf("Opera") > -1) { + sBrowser = "Opera"; +} else if (sUsrAg.indexOf("Firefox") > -1) { + sBrowser = "Mozilla Firefox"; +} else if (sUsrAg.indexOf("MSIE") > -1) { + sBrowser = "Microsoft Internet Explorer"; +} + +alert("You are using: " + sBrowser);</pre> + +<h3 id="Example_2_Browser_detect_and_return_an_index">Example #2: Browser detect and return an index</h3> + +<pre class="brush: js">function getBrowserId () { + + var + aKeys = ["MSIE", "Firefox", "Safari", "Chrome", "Opera"], + sUsrAg = navigator.userAgent, nIdx = aKeys.length - 1; + + for (nIdx; nIdx > -1 && sUsrAg.indexOf(aKeys[nIdx]) === -1; nIdx--); + + return nIdx + +} + +console.log(getBrowserId());</pre> + +<h2 id="Specification" name="Specification">規範</h2> + +<ul> + <li>{{SpecName("HTML5 W3C", "webappapis.html#the-navigator-object","window.navigator")}}</li> + <li>{{SpecName("HTML5.1", "webappapis.html#the-navigator-object", "window.navigator")}}</li> + <li>{{SpecName("HTML WHATWG", "timers.html#the-navigator-object", "window.navigator")}}</li> +</ul> + +<h2 id="See_also" name="See_also">參見</h2> diff --git a/files/zh-tw/web/api/window/opener/index.html b/files/zh-tw/web/api/window/opener/index.html new file mode 100644 index 0000000000..e7ddb3e8c1 --- /dev/null +++ b/files/zh-tw/web/api/window/opener/index.html @@ -0,0 +1,30 @@ +--- +title: Window.opener +slug: Web/API/Window/opener +translation_of: Web/API/Window/opener +--- +<div>{{APIRef}}</div> + +<h2 id="Summary" name="Summary">概要</h2> + +<p>回傳一個開啟目前視窗（window）之視窗的參考（reference）。</p> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox"><var>objRef</var> = window.opener; +</pre> + +<h2 id="Example" name="Example">範例</h2> + +<pre class="brush:js">if (window.opener != indexWin) { + referToTop(window.opener); +} +</pre> + +<h2 id="Notes" name="Notes">備註</h2> + +<p>當一個視窗是由另一個視窗所開啟（使用 {{domxref("Window.open")}} 或一個帶有 <code><a href="/zh-TW/docs/Web/HTML/Element/a#attr-target">target</a></code> 屬性設定的連結），被開啟的這個視窗會於 <strong>window.opener</strong> 保留開啟它的第一個視窗之參考。假如目前的視窗沒有開啟它的視窗，則會回傳 NULL。</p> + +<p>Windows Phone 瀏覽器不支援 <code>window.opener</code>（測試版本為 Microsoft Edge 25.10586.36.0）。若 <code>window.opener</code> 為不同的安全區域（security zone），則 IE 也不支援此屬性。</p> + +<p>在 <a href="https://caniuse.com/#search=noopener">某些瀏覽器</a>中，在發起連結的標籤中加入 <code>rel="noopener"</code> 屬性，可以阻止設定 <code>window.opener</code> 視窗參考。</p> diff --git a/files/zh-tw/web/api/window/orientationchange_event/index.html b/files/zh-tw/web/api/window/orientationchange_event/index.html new file mode 100644 index 0000000000..fe5264163c --- /dev/null +++ b/files/zh-tw/web/api/window/orientationchange_event/index.html @@ -0,0 +1,69 @@ +--- +title: 'Window: orientationchange event' +slug: Web/API/Window/orientationchange_event +tags: + - Sensors +translation_of: Web/API/Window/orientationchange_event +--- +<div>{{APIRef}}</div> + +<p><code>orientationchange</code> 事件在設備方向改變時被觸發。</p> + +<table class="properties"> + <tbody> + <tr> + <th scope="row">冒泡</th> + <td>No</td> + </tr> + <tr> + <th scope="row">可取消</th> + <td>No</td> + </tr> + <tr> + <th scope="row">介面</th> + <td>{{domxref("Event")}}</td> + </tr> + <tr> + <th scope="row">事件處理器</th> + <td><code><a href="/zh-TW/docs/Web/API/Window/onorientationchange">onorientationchange</a></code></td> + </tr> + </tbody> +</table> + +<h2 id="範例">範例</h2> + +<p>可於 <code><a href="/zh-TW/docs/Web/API/EventTarget/addEventListener">addEventListener</a></code> 方法中使用 <code>abort</code> 事件：</p> + +<pre class="brush:js;">window.addEventListener("orientationchange", function() { + console.log("the orientation of the device is now " + screen.orientation.angle); +}); +</pre> + +<p>或使用 <code><a href="/zh-TW/docs/Web/API/Window/onorientationchange">onorientationchange</a></code> 事件處理器屬性：</p> + +<pre class="brush: js">window.onorientationchange = function() { + console.log("the orientation of the device is now " + screen.orientation.angle); +};</pre> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Specification</th> + <th scope="col">Status</th> + </tr> + <tr> + <td>{{SpecName('Compat', '#event-orientationchange', 'orientationchange')}}</td> + <td>{{Spec2('Compat')}}</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<div class="hidden"> +<p>The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> +</div> + +<p>{{Compat("api.Window.orientationchange_event")}}</p> diff --git a/files/zh-tw/web/api/window/print/index.html b/files/zh-tw/web/api/window/print/index.html new file mode 100644 index 0000000000..4e2a543cf5 --- /dev/null +++ b/files/zh-tw/web/api/window/print/index.html @@ -0,0 +1,46 @@ +--- +title: Window.print() +slug: Web/API/Window/print +translation_of: Web/API/Window/print +--- +<p>{{ ApiRef() }}</p> + +<h2 id="Summary" name="Summary">摘要</h2> + +<p>打開列印視窗來列印當前的文件。</p> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="eval">window.print() +</pre> + +<h2 id="Specification" name="Specification">注釋</h2> + +<p>Starting with Chrome {{CompatChrome(46.0)}} this method is blocked inside an {{htmlelement("iframe")}} unless its sandbox attribute has the value <code>allow-modals</code>.</p> + +<h2 id="Specification" name="Specification">規範</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('HTML WHATWG', 'timers-and-user-prompts.html#printing', 'print()')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/en/Printing" title="en/Printing">Printing</a></li> + <li>{{ domxref("window.onbeforeprint") }}</li> + <li>{{ domxref("window.onafterprint") }}</li> +</ul> + +<p>{{ languages( { "ja": "ja/DOM/window.print", "it": "it/DOM/window.print" , "zh-cn": "zh-cn/DOM/window.print" } ) }}</p> diff --git a/files/zh-tw/web/api/window/requestidlecallback/index.html b/files/zh-tw/web/api/window/requestidlecallback/index.html new file mode 100644 index 0000000000..743e7b2a39 --- /dev/null +++ b/files/zh-tw/web/api/window/requestidlecallback/index.html @@ -0,0 +1,119 @@ +--- +title: window.requestIdleCallback() +slug: Web/API/Window/requestIdleCallback +translation_of: Web/API/Window/requestIdleCallback +--- +<div>{{APIRef("HTML DOM")}}{{SeeCompatTable}}</div> + +<p>The <code><strong>window.requestIdleCallback()</strong></code> method queues a function to be called during a browser's idle periods. This enables developers to perform background and low priority work on the main event loop, without impacting latency-critical events such as animation and input response. Functions are generally called in first-in-first-out order; however, callbacks which have a <code>timeout</code> specified may be called out-of-order if necessary in order to run them before the timeout elapses.</p> + +<div class="note"> +<p>You can call <code>requestIdleCallback()</code> within an idle callback function to schedule another callback to take place no sooner than the next pass through the event loop.</p> +</div> + +<h2 id="Syntax" name="Syntax">Syntax</h2> + +<pre class="syntaxbox"><code>var <em>handle</em> = w<em>indow</em>.requestIdleCallback(<em>callback</em>[, <em>options</em>])</code></pre> + +<h3 id="Returns" name="Returns">Return value</h3> + +<p>An ID which can be used to cancel the callback by passing it into the {{domxref("window.cancelIdleCallback()")}} method.</p> + +<h3 id="Parameters" name="Parameters">Parameters</h3> + +<dl> + <dt><code>callback</code></dt> + <dd>A reference to a function that should be called in the near future, when the event loop is idle. The callback function is passed a {{domxref("IdleDeadline")}} object describing the amount of time available and whether or not the callback has been run because the timeout period expired.</dd> + <dt><code>options</code> {{optional_inline}}</dt> + <dd>Contains optional configuration parameters. Currently only one property is defined: + <ul> + <li><code>timeout</code>: If <code>timeout</code> is specified and has a positive value, and the callback has not already been called by the time timeout milliseconds have passed, the timeout will be called during the next idle period, even if doing so risks causing a negative performance impact.</li> + </ul> + </dd> +</dl> + +<h2 id="Specifications" name="Specifications">Example</h2> + +<p>See our <a href="/en-US/docs/Web/API/Background_Tasks_API#Example">complete example</a> in the article <a href="/en-US/docs/Web/API/Background_Tasks_API">Cooperative Scheduling of Background Tasks API</a>.</p> + +<h2 id="Specifications" name="Specifications">Specifications</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th>Specification</th> + <th>Status</th> + <th>Comment</th> + </tr> + <tr> + <td>{{SpecName('Background Tasks')}}</td> + <td>{{Spec2('Background Tasks')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility" name="Browser_compatibility">Browser compatibility</h2> + +<p>{{CompatibilityTable}}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatChrome(47)}}</td> + <td>{{CompatGeckoDesktop(53)}} [1]</td> + <td>{{CompatNo}}</td> + <td>{{CompatOpera(34)}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android Webview</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatChrome(47)}}</td> + <td>{{CompatChrome(47)}}</td> + <td>{{CompatGeckoMobile(53)}} [1]</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] <code>requestIdleCallback()</code> is implemented in Firefox 53 but is disabled by default; to enable it, set the preference <code>dom.requestIdleCallback.enabled</code> to <code>true</code>. It is enabled by default starting in Firefox 55.</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li>{{domxref("window.cancelIdleCallback()")}}</li> + <li>{{domxref("IdleDeadline")}}</li> + <li>{{domxref("window.setTimeout()")}}</li> + <li>{{domxref("window.setInterval()")}}</li> +</ul> diff --git a/files/zh-tw/web/api/window/sessionstorage/index.html b/files/zh-tw/web/api/window/sessionstorage/index.html new file mode 100644 index 0000000000..696367e872 --- /dev/null +++ b/files/zh-tw/web/api/window/sessionstorage/index.html @@ -0,0 +1,94 @@ +--- +title: Window.sessionStorage +slug: Web/API/Window/sessionStorage +tags: + - API + - Property + - Storage + - WindowSessionStorage + - localStorage +translation_of: Web/API/Window/sessionStorage +--- +<p>{{APIRef()}}</p> + +<p><code>sessionStorage</code> 屬性能讓開發人員訪問當前 origin 的 {{DOMxRef("Storage")}} 物件。<code>sessionStorage</code> 跟 {{DOMxRef("Window.localStorage", "localStorage")}} 很相似：唯一不同的地方是存放在 <code>localStorage</code> 的資料並沒有過期的時效；而存放在 <code>sessionStorage</code> 的資料則會在頁面 session 結束時清空。只要該頁面頁面(頁籤)沒被關閉或者有還原(restore)該頁面，資料就會保存。<strong>開啟新頁籤或視窗會產生一個新的sessionStorage</strong>，跟Session與Cookies的做法不大一樣。 + +</p> + +<p>另應該注意：不論資料放在 <code>sessionStorage</code> 還是 <code>localStorage</code>，都被<strong>限制在該網站的規範內，其他網站無法存取</strong>。</p> + +<h2 id="語法">語法</h2> + +<pre class="brush: js">// 將資料存到sessionStorage +sessionStorage.setItem('key', 'value'); + +// 從sessionStorage取得之前存的資料 +var data = sessionStorage.getItem('key'); + +// 從sessionStorage移除之前存的資料 +sessionStorage.removeItem('key'); + +// 從sessionStorage移除之前存的所有資料 +sessionStorage.clear(); +</pre> + +<h3 id="回傳值">回傳值</h3> + +<p>一個 {{DOMxRef("Storage")}} 物件.</p> + +<h2 id="範例">範例</h2> + +<p>下面簡短的程式碼，訪問了當前域名下的 session {{DOMxRef("Storage")}} 物件，並使用 {{DOMxRef("Storage.setItem()")}} 添加了資料單元。</p> + +<pre class="brush: js;">sessionStorage.setItem('myCat', 'Tom');</pre> + +<p>以下提供的範例為將文字輸入元件的內容自動保存，如果瀏覽器不小心重新整理，在頁面恢復後，會自動將內容還原，不會造成尚未送出的資料被清空。</p> + +<pre class="brush: js">// 取得我們要保留內容的text field元件 +var field = document.getElementById("field"); + +// 檢查是否有之前的<strong>autosave</strong>的內容 +// 這段程式碼會在瀏覽器進入該頁面時被執行 +if (sessionStorage.getItem("autosave")) { + // 還原先前的內容到指定的text field + field.value = sessionStorage.getItem("autosave"); +} + +// 註冊事件監聽text field內容的變化 +field.addEventListener("change", function() { + // 並儲存變化後的內容至sessionStorage的物件裡 + sessionStorage.setItem("autosave", field.value); +});</pre> + +<div class="note"> +<p><strong>備註</strong>: 完整的範例可參考這篇文章: <a href="/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API">Using the Web Storage API</a>。</p> +</div> + +<h2 id="規格">規格</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規格</th> + <th scope="col">狀態</th> + <th scope="col">註解</th> + </tr> + <tr> + <td>{{SpecName('HTML WHATWG', 'webstorage.html#dom-sessionstorage', 'sessionStorage')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{Compat("api.Window.sessionStorage")}}</p> + + +<h2 id="相關內容">相關內容</h2> + +<ul> + <li><a href="/zh-TW/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API">Using the Web Storage API</a></li> + <li>{{domxref("Window.localStorage")}}</li> +</ul> diff --git a/files/zh-tw/web/api/window/sidebar/adding_search_engines_from_web_pages/index.html b/files/zh-tw/web/api/window/sidebar/adding_search_engines_from_web_pages/index.html new file mode 100644 index 0000000000..020f1be65e --- /dev/null +++ b/files/zh-tw/web/api/window/sidebar/adding_search_engines_from_web_pages/index.html @@ -0,0 +1,35 @@ +--- +title: 自網頁添加搜尋引擎 +slug: Web/API/Window/sidebar/Adding_search_engines_from_Web_pages +tags: + - 搜尋模組 +translation_of: Web/OpenSearch +--- +<p>Firefox 可以用 JavaScript 安裝搜尋引擎模組，且支援 <a href="zh_tw/%e8%a3%bd%e4%bd%9c_OpenSearch_%e6%90%9c%e5%b0%8b%e6%a8%a1%e7%b5%84">OpenSearch</a> 及 Sherlock 兩種模組格式。 +</p> +<div class="note"><b>註：</b> 自 Firefox 2 起，偏好的模組格式為 OpenSearch。</div> +<p>當 JavaScript 程式碼要安裝新的搜尋模組時，Firefox 會詢問使用者是否允許安裝。 +</p> +<h2 id=".E5.AE.89.E8.A3.9D_OpenSearch_.E6.A8.A1.E7.B5.84">安裝 OpenSearch 模組</h2> +<p>要安裝 OpenSearch 模組，必須使用 <code>window.external.AddSearchProvider()</code> DOM 方法。此方法的語法為： +</p> +<pre class="eval">window.external.AddSearchProvider(<i>搜尋模組 URL</i>); +</pre> +<p>其中 <i>搜尋模組 URL</i> 為搜尋引擎模組之 XML 檔的絕對連結 URL。 +</p> +<div class="note"><b>注意：</b> OpenSearch 自 Firefox 2 起的版本才支援。</div> +<h2 id=".E5.AE.89.E8.A3.9D_Sherlock_.E6.A8.A1.E7.B5.84">安裝 Sherlock 模組</h2> +<p>要安裝 Sherlock 模組，必須叫用 <code>window.sidebar.addSearchEngine()</code> 方法，語法為： +</p> +<pre class="eval">window.sidebar.addSearchEngine(<i>搜尋模組 URL</i>, <i>圖示 URL</i>, <i>建議名稱</i>, <i>建議分類</i>); +</pre> +<ul><li> <code>搜尋模組 URL</code> 參數為欲安裝的 Sherlock 格式檔（「.src」檔）URL。 +</li><li> <code>圖示 URL</code> 參數為此模組的圖示 URL。 +</li><li> <code>建議名稱</code> 參數僅於請求使用者確認安裝模組時才使用，安裝時訊息為「Do you want to install <i>建議名稱</i> from <i>搜尋模組 URL</i>？」 +</li><li> <code>建議分類</code> 參數並不使用，可以指定為空字串（<code>""</code>）或 <code>null</code>。 +</li></ul> +<p>Sherlock 的相關資訊可參考 <a class=" external" href="http://developer.apple.com/macosx/sherlock/">http://developer.apple.com/macosx/sherlock/</a> +</p> +<div class="noinclude"> +</div> +{{ languages( { "ca": "ca/Addici\u00f3_de_motors_de_cerca_a_les_p\u00e0gines_web", "en": "en/Adding_search_engines_from_web_pages", "es": "es/A\u00f1adir_motores_de_b\u00fasqueda_desde_p\u00e1ginas_web", "fr": "fr/Ajout_de_moteurs_de_recherche_depuis_des_pages_Web", "it": "it/Installare_plugin_di_ricerca_dalle_pagine_web", "ja": "ja/Adding_search_engines_from_web_pages", "pl": "pl/Dodawanie_wyszukiwarek_z_poziomu_stron_WWW" } ) }} diff --git a/files/zh-tw/web/api/window/sidebar/index.html b/files/zh-tw/web/api/window/sidebar/index.html new file mode 100644 index 0000000000..280b5dcce3 --- /dev/null +++ b/files/zh-tw/web/api/window/sidebar/index.html @@ -0,0 +1,56 @@ +--- +title: Window.sidebar +slug: Web/API/Window/sidebar +tags: + - DOM + - NeedsTranslation + - Non-standard + - Property + - Reference + - TopicStub + - Window +translation_of: Web/API/Window/sidebar +--- +<div>{{APIRef}} {{Non-standard_header}}</div> + +<p>Returns a sidebar object, which contains several methods for registering add-ons with the browser.</p> + +<h2 id="Notes" name="Notes">Notes</h2> + +<p>The sidebar object returned has the following methods:</p> + +<table class="fullwidth-table"> + <tbody> + <tr> + <th>Method</th> + <th>Description (SeaMonkey)</th> + <th>Description (Firefox)</th> + </tr> + <tr> + <td><code>addPanel(<var>title</var>, <var>contentURL</var>, "")</code></td> + <td>Adds a sidebar panel.</td> + <td rowspan="2">Obsolete since Firefox 23 (only present in SeaMonkey).<br> + End users can use the "load this bookmark in the sidebar" option instead. Also see <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Creating_a_Firefox_sidebar">Creating a Firefox sidebar.</a></td> + </tr> + <tr> + <td><code>addPersistentPanel(<var>title</var>, <var>contentURL</var>, "")</code></td> + <td>Adds a sidebar panel, which is able to work in the background.</td> + </tr> + <tr> + <td><code>AddSearchProvider(<em>descriptionURL)</em></code></td> + <td colspan="2">Installs a search provider (OpenSearch). <a href="/en-US/docs/Web/API/Window/sidebar/Adding_search_engines_from_Web_pages#Installing_OpenSearch_plugins" title="Adding_search_engines_from_web_pages">Adding OpenSearch search engines </a>contains more details. Added in Firefox 2.</td> + </tr> + <tr> + <td><code>addSearchEngine(<var>engineURL</var>, <var>iconURL</var>, <var>suggestedTitle</var>, <var>suggestedCategory</var>)</code> {{Obsolete_inline(44)}}</td> + <td colspan="2">Installs a search engine (Sherlock). <a href="/en-US/docs/Web/API/Window/sidebar/Adding_search_engines_from_Web_pages#Installing_Sherlock_plugins" title="Adding_search_engines_from_web_pages">Adding Sherlock search engines </a>contains more details.</td> + </tr> + <tr> + <td><code>IsSearchProviderInstalled(<em>descriptionURL)</em></code></td> + <td colspan="2">Indicates if a specific search provider (OpenSearch) is installed.</td> + </tr> + </tbody> +</table> + +<h2 id="Specification" name="Specification">Specification</h2> + +<p>Mozilla-specific. Not part of any standard.</p> diff --git a/files/zh-tw/web/api/windowbase64/index.html b/files/zh-tw/web/api/windowbase64/index.html new file mode 100644 index 0000000000..804f10ab1a --- /dev/null +++ b/files/zh-tw/web/api/windowbase64/index.html @@ -0,0 +1,113 @@ +--- +title: WindowBase64 +slug: Web/API/WindowBase64 +translation_of: Web/API/WindowOrWorkerGlobalScope +--- +<p>{{APIRef("HTML DOM")}}</p> + +<p>The <code><strong>WindowBase64</strong></code> helper contains utility methods to convert data to and from base64, a binary-to-text encoding scheme. For example it is used in <a href="/en-US/docs/data_URIs">data URIs</a>.</p> + +<p>There is no object of this type, though the context object, either the {{domxref("Window")}} for regular browsing scope, or the {{domxref("WorkerGlobalScope")}} for workers, implements it.</p> + +<h2 id="屬性">屬性</h2> + +<p><em>This helper neither defines nor inherits any properties.</em></p> + +<h2 id="方法">方法</h2> + +<p><em>This helper does not inherit any methods.</em></p> + +<dl> + <dt>{{domxref("WindowBase64.atob()")}}</dt> + <dd>Decodes a string of data which has been encoded using base-64 encoding.</dd> + <dt>{{domxref("WindowBase64.btoa()")}}</dt> + <dd>Creates a base-64 encoded ASCII string from a string of binary data.</dd> +</dl> + +<h2 id="規範">規範</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', '#windowbase64', 'WindowBase64')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>No change since the latest snapshot, {{SpecName("HTML5.1")}}.</td> + </tr> + <tr> + <td>{{SpecName('HTML5.1', '#windowbase64', 'WindowBase64')}}</td> + <td>{{Spec2('HTML5.1')}}</td> + <td>Snapshot of {{SpecName("HTML WHATWG")}}. No change.</td> + </tr> + <tr> + <td>{{SpecName("HTML5 W3C", "#windowbase64", "WindowBase64")}}</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="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Firefox (Gecko)</th> + <th>Chrome</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatGeckoDesktop(1)}} [1]</td> + <td>{{CompatVersionUnknown}}</td> + <td>10.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Firefox Mobile (Gecko)</th> + <th>Android</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatGeckoMobile(1)}}</td> + <td rowspan="1">{{CompatVersionUnknown}}</td> + <td rowspan="1">{{CompatVersionUnknown}}</td> + <td rowspan="1">{{CompatVersionUnknown}}</td> + <td rowspan="1">{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] <code>atob()</code> is also available to XPCOM components implemented in JavaScript, even though {{domxref("Window")}} is not the global object in components.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/Web/API/WindowBase64/Base64_encoding_and_decoding">Base64 encoding and decoding</a></li> + <li>{{domxref("Window")}}, {{domxref("WorkerGlobalScope")}}, {{domxref("DedicatedWorkerGlobalScope")}}, {{domxref("SharedWorkerGlobalScope")}}, and {{domxref("ServiceWorkerGlobalScope")}}</li> +</ul> diff --git a/files/zh-tw/web/api/windoweventhandlers/index.html b/files/zh-tw/web/api/windoweventhandlers/index.html new file mode 100644 index 0000000000..d3d29ddb63 --- /dev/null +++ b/files/zh-tw/web/api/windoweventhandlers/index.html @@ -0,0 +1,182 @@ +--- +title: WindowEventHandlers +slug: Web/API/WindowEventHandlers +translation_of: Web/API/WindowEventHandlers +--- +<div>{{APIRef("HTML DOM")}}</div> + +<p><strong><code>WindowEventHandlers</code></strong> mixin describes the event handlers common to several interfaces like {{domxref("Window")}}, or {{domxref("HTMLBodyElement")}} and {{domxref("HTMLFrameSetElement")}}. Each of these interfaces can implement additional specific event handlers.</p> + +<p><code>WindowEventHandlers</code> is a not an interface and no object of this type can be created.</p> + +<h2 id="屬性">屬性</h2> + +<p><em>The events properties, of the form <code>onXYZ</code>, are defined on the {{domxref("WindowEventHandlers")}}, and implemented by {{domxref("Window")}}, and {{domxref("WorkerGlobalScope")}} for Web Workers.</em></p> + +<dl> + <dt>{{domxref("WindowEventHandlers.onafterprint")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("afterprint")}} event is raised.</dd> + <dt>{{domxref("WindowEventHandlers.onbeforeprint")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("beforeprint")}} event is raised.</dd> + <dt>{{domxref("WindowEventHandlers.onbeforeunload")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("beforeunload")}} event is raised.</dd> + <dt>{{domxref("WindowEventHandlers.onhashchange")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("hashchange")}} event is raised.</dd> + <dt>{{domxref("WindowEventHandlers.onlanguagechange")}} {{experimental_inline}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("languagechange")}} event is raised.</dd> + <dt>{{domxref("WindowEventHandlers.onmessage")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("message")}} event is raised.</dd> + <dt>{{domxref("WindowEventHandlers.onoffline")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("offline")}} event is raised.</dd> + <dt>{{domxref("WindowEventHandlers.ononline")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("online")}} event is raised.</dd> + <dt>{{domxref("WindowEventHandlers.onpagehide")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("pagehide")}} event is raised.</dd> + <dt>{{domxref("WindowEventHandlers.onpageshow")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("pageshow")}} event is raised.</dd> + <dt>{{domxref("WindowEventHandlers.onpopstate")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("popstate")}} event is raised.</dd> + <dt>{{domxref("WindowEventHandlers.onstorage")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("storage")}} event is raised.</dd> + <dt>{{domxref("WindowEventHandlers.onunhandledrejection")}} {{experimental_inline}}</dt> + <dd>An event handler for unhandled {{jsxref("Promise")}} rejection events.</dd> + <dt>{{domxref("WindowEventHandlers.onunload")}}</dt> + <dd>Is an {{domxref("EventHandler")}} representing the code to be called when the {{event("unload")}} event is raised.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<p><em>This interface defines no method.</em></p> + +<h2 id="規範">規範</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', '#windoweventhandlers', 'GlobalEventHandlers')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>No change since the latest snapshot, {{SpecName("HTML5.1")}}.</td> + </tr> + <tr> + <td>{{SpecName('HTML5.1', '#windoweventhandlers', 'GlobalEventHandlers')}}</td> + <td>{{Spec2('HTML5.1')}}</td> + <td>Snapshot of {{SpecName("HTML WHATWG")}}. Added <code>onlanguage</code> since the {{SpecName("HTML5 W3C")}} snapshot.</td> + </tr> + <tr> + <td>{{SpecName("HTML5 W3C", "#windoweventhandlers", "GlobalEventHandlers")}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>Snapshot of {{SpecName("HTML WHATWG")}}. Creation of <code>WindowEventHandlers</code> (properties where on the target before it).</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Firefox (Gecko)</th> + <th>Chrome</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>onhashchange</code></td> + <td>{{CompatGeckoDesktop(1.9.2)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>onlanguage</code>{{experimental_inline}}</td> + <td>{{CompatGeckoDesktop(32)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>onstorage</code></td> + <td>{{CompatGeckoDesktop(45)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Firefox Mobile (Gecko)</th> + <th>Android</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td rowspan="1">{{CompatUnknown}}</td> + <td rowspan="1">{{CompatUnknown}}</td> + <td rowspan="1">{{CompatUnknown}}</td> + <td rowspan="1">{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>onhashchange</code></td> + <td>{{CompatGeckoMobile(1.9.2)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>onlanguage</code>{{experimental_inline}}</td> + <td>{{CompatGeckoMobile(32)}}</td> + <td rowspan="1">{{CompatUnknown}}</td> + <td rowspan="1">{{CompatUnknown}}</td> + <td rowspan="1">{{CompatUnknown}}</td> + <td rowspan="1">{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>onstorage</code></td> + <td>{{CompatGeckoDesktop(45)}}</td> + <td rowspan="1">{{CompatUnknown}}</td> + <td rowspan="1">{{CompatUnknown}}</td> + <td rowspan="1">{{CompatUnknown}}</td> + <td rowspan="1">{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("Window")}} and {{domxref("WorkerGlobalScope")}}</li> +</ul> diff --git a/files/zh-tw/web/api/windoweventhandlers/onbeforeunload/index.html b/files/zh-tw/web/api/windoweventhandlers/onbeforeunload/index.html new file mode 100644 index 0000000000..66ba170df5 --- /dev/null +++ b/files/zh-tw/web/api/windoweventhandlers/onbeforeunload/index.html @@ -0,0 +1,153 @@ +--- +title: WindowEventHandlers.onbeforeunload +slug: Web/API/WindowEventHandlers/onbeforeunload +translation_of: Web/API/WindowEventHandlers/onbeforeunload +--- +<div> +<div>{{APIRef("HTML DOM")}}</div> +</div> + +<div> </div> + +<p><code><strong>WindowEventHandlers.onbeforeunload</strong></code> 事件处理函数包含的代码将在 {{event("beforeunload")}} 发出时被执行。当 window 准备释放它的资源时，该事件被触发。此时 document 仍然可见，且事件是仍然可被取消的。</p> + +<div class="note"> +<p><strong>注意:</strong> 为了避免不必要的弹出窗口，除非页面已经有过互动，否则可能不会显示beforeunload创建的询问窗口。对于特定的浏览器列表，请参阅浏览器兼容性部分。</p> +</div> + +<h2 id="Syntax" name="Syntax">语法</h2> + +<pre class="syntaxbox">window.onbeforeunload = <var>funcRef</var></pre> + +<ul> + <li><code>funcRef</code> 是函数或函数表达式的引用。</li> + <li>这个函数应该设置一个字符串到事件对象的 returnValue 属性上，且返回该字符串。</li> +</ul> + +<h2 id="Example" name="Example">示例</h2> + +<pre class="brush:js">window.onbeforeunload = function(e) { + var dialogText = 'Dialog text here'; + e.returnValue = dialogText; + return dialogText; +}; +</pre> + +<h2 id="注意">注意</h2> + +<p>当事件返回了一个非空值时，将需要用户确认是否 unload 页面。在大部分浏览器中，事件的返回值将在对话框中显示。在 Firefox 4 及以后，返回值将不会显示给用户。作为替代，Firefox将会显示"This page is asking you to confirm that you want to leave - data you have entered may not be saved." 请查看{{bug("588292")}}.</p> + +<p>Since 25 May 2011, the HTML5 specification states that calls to {{domxref("window.alert()")}}, {{domxref("window.confirm()")}}, and {{domxref("window.prompt()")}} methods may be ignored during this event. See the <a href="http://www.w3.org/TR/html5/webappapis.html#user-prompts">HTML5 specification</a> for more details.</p> + +<p>Note also that various mobile browsers ignore the result of the event (that is, they do not ask the user for confirmation). Firefox has a hidden preference in about:config to do the same. In essence this means the user always confirms that the document may be unloaded.</p> + +<p>You <em>can</em> and <em>should</em> handle this event through {{domxref("EventTarget.addEventListener","window.addEventListener()")}} and the {{event("beforeunload")}} event. More documentation is available there.</p> + +<h2 id="Specifications">Specifications</h2> + +<p>The event was originally introduced by Microsoft in Internet Explorer 4 and standardized in the HTML5 specification.</p> + +<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', '#windoweventhandlers', 'GlobalEventHandlers')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName('HTML5.1', '#windoweventhandlers', 'GlobalEventHandlers')}}</td> + <td>{{Spec2('HTML5.1')}}</td> + <td> </td> + </tr> + <tr> + <td>{{SpecName("HTML5 W3C", "#windoweventhandlers", "GlobalEventHandlers")}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatChrome(1.0)}}</td> + <td>1</td> + <td>4</td> + <td>12</td> + <td>3</td> + </tr> + <tr> + <td>Custom text support removed</td> + <td>{{CompatChrome(51.0)}}</td> + <td>{{CompatGeckoMobile("44.0")}}</td> + <td> </td> + <td>38</td> + <td><a href="https://developer.apple.com/library/mac/releasenotes/General/WhatsNewInSafari/Articles/Safari_9_1.html">9.1</a></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>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + <th>Chrome for Android</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>(no) <a href="https://bugs.webkit.org/show_bug.cgi?id=19324">defect</a></td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>Custom text support removed</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatChrome(51.0)}}</td> + <td>{{CompatGeckoMobile("44.0")}}</td> + <td> </td> + <td> </td> + <td> </td> + <td>{{CompatChrome(51.0)}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="See also" name="See also">See also</h2> + +<ul> + <li><a href="http://msdn.microsoft.com/en-us/library/ms536907(VS.85).aspx">MSDN: onbeforeunload event</a></li> +</ul> diff --git a/files/zh-tw/web/api/windoworworkerglobalscope/btoa/index.html b/files/zh-tw/web/api/windoworworkerglobalscope/btoa/index.html new file mode 100644 index 0000000000..93d63b6010 --- /dev/null +++ b/files/zh-tw/web/api/windoworworkerglobalscope/btoa/index.html @@ -0,0 +1,136 @@ +--- +title: WindowOrWorkerGlobalScope.btoa() +slug: Web/API/WindowOrWorkerGlobalScope/btoa +translation_of: 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> diff --git a/files/zh-tw/web/api/windoworworkerglobalscope/index.html b/files/zh-tw/web/api/windoworworkerglobalscope/index.html new file mode 100644 index 0000000000..9fb46d21d5 --- /dev/null +++ b/files/zh-tw/web/api/windoworworkerglobalscope/index.html @@ -0,0 +1,98 @@ +--- +title: WindowOrWorkerGlobalScope +slug: Web/API/WindowOrWorkerGlobalScope +tags: + - API + - HTML DOM + - NeedsTranslation + - Service Worker + - TopicStub + - Window + - WindowOrWorkerGlobalScope + - Worker + - WorkerGlobalScope +translation_of: Web/API/WindowOrWorkerGlobalScope +--- +<div>{{ApiRef()}}</div> + +<p><span class="seoSummary">The <strong><code>WindowOrWorkerGlobalScope</code></strong> mixin describes several features common to the {{domxref("Window")}} and {{domxref("WorkerGlobalScope")}} interfaces.</span> Each of these interfaces can, of course, add more features in addition to the ones listed below.</p> + +<div class="note"> +<p><strong>Note</strong>: <code>WindowOrWorkerGlobalScope</code> is a mixin and not an interface; you can't actually create an object of type <code>WindowOrWorkerGlobalScope</code>.</p> +</div> + +<h2 id="Properties_2">Properties</h2> + +<p>These properties are defined on the {{domxref("WindowOrWorkerGlobalScope")}} mixin, and implemented by {{domxref("Window")}} and {{domxref("WorkerGlobalScope")}}.</p> + +<div id="Properties"> +<dl> + <dt>{{domxref("WindowOrWorkerGlobalScope.caches")}} {{readOnlyinline}}</dt> + <dd>Returns the {{domxref("CacheStorage")}} object associated with the current context. This object enables functionality such as storing assets for offline use, and generating custom responses to requests.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.crossOriginIsolated")}} {{readOnlyinline}}</dt> + <dd>Returns a boolean value that indicates whether a {{jsxref("SharedArrayBuffer")}} can be sent via a {{domxref("Window.postMessage()")}} call.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.indexedDB")}} {{readonlyInline}}</dt> + <dd>Provides a mechanism for applications to asynchronously access capabilities of indexed databases; returns an {{domxref("IDBFactory")}} object.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.isSecureContext")}} {{readOnlyinline}}</dt> + <dd>Returns a boolean indicating whether the current context is secure (<code>true</code>) or not (<code>false</code>).</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.origin")}} {{readOnlyinline}}</dt> + <dd>Returns the origin of the global scope, serialized as a string.</dd> +</dl> +</div> + +<h2 id="Methods">Methods</h2> + +<p>These methods are defined on the {{domxref("WindowOrWorkerGlobalScope")}} mixin, and implemented by {{domxref("Window")}} and {{domxref("WorkerGlobalScope")}}.</p> + +<dl> + <dt>{{domxref("WindowOrWorkerGlobalScope.atob()")}}</dt> + <dd>Decodes a string of data which has been encoded using base-64 encoding.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.btoa()")}}</dt> + <dd>Creates a base-64 encoded ASCII string from a string of binary data.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.clearInterval()")}}</dt> + <dd>Cancels the repeated execution set using {{domxref("WindowOrWorkerGlobalScope.setInterval()")}}.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.clearTimeout()")}}</dt> + <dd>Cancels the delayed execution set using {{domxref("WindowOrWorkerGlobalScope.setTimeout()")}}.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.createImageBitmap()")}}</dt> + <dd>Accepts a variety of different image sources, and returns a {{domxref("Promise")}} which resolves to an {{domxref("ImageBitmap")}}. Optionally the source is cropped to the rectangle of pixels originating at <em>(</em><code>sx</code>, <code>sy</code><em>)</em> with width <code>sw</code>, and height <code>sh</code>.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.fetch()")}}</dt> + <dd>Starts the process of fetching a resource from the network.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.queueMicrotask()")}}</dt> + <dd>Enqueues a microtask—a short function to be executed after execution of the JavaScript code completes and control isn't being returned to a JavaScript caller, but before handling callbacks and other tasks. This lets your code run without interfering with other, possibly higher priority, code, but <em>before</em> the browser runtime regains control, potentially depending upon the work you need to complete.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.setInterval()")}}</dt> + <dd>Schedules a function to execute every time a given number of milliseconds elapses.</dd> + <dt>{{domxref("WindowOrWorkerGlobalScope.setTimeout()")}}</dt> + <dd>Schedules a function to execute in a given amount of time.</dd> +</dl> + +<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",'webappapis.html#windoworworkerglobalscope-mixin', '<code>WindowOrWorkerGlobalScope</code> mixin')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>This is where the main mixin is defined.</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + + + +<p>{{Compat("api.WindowOrWorkerGlobalScope")}}</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li>{{domxref("Window")}}</li> + <li>{{domxref("WorkerGlobalScope")}}</li> +</ul> diff --git a/files/zh-tw/web/api/windoworworkerglobalscope/setinterval/index.html b/files/zh-tw/web/api/windoworworkerglobalscope/setinterval/index.html new file mode 100644 index 0000000000..7685a8f754 --- /dev/null +++ b/files/zh-tw/web/api/windoworworkerglobalscope/setinterval/index.html @@ -0,0 +1,627 @@ +--- +title: WindowOrWorkerGlobalScope.setInterval() +slug: Web/API/WindowOrWorkerGlobalScope/setInterval +translation_of: Web/API/WindowOrWorkerGlobalScope/setInterval +--- +<div>{{APIRef("HTML DOM")}}</div> + +<p><span class="seoSummary"><strong><code>setInterval()</code></strong> 函式, {{domxref("Window")}} 與 {{domxref("Worker")}} 介面皆提供此一函式, 此函式作用為重複地執行一個函式呼叫或一個程式碼片斷, 每一次執行間隔固定的延遲時間.</span> 此函式呼叫時將傳回一個間隔代碼(Interval ID)用以識別該間隔程序, 因此後續您可以呼叫 {{domxref("WindowOrWorkerGlobalScope.clearInterval", "clearInterval()")}} 函式移除該間隔程序. 此函式為由 {{domxref("WindowOrWorkerGlobalScope")}} 混合定義.</p> + +<h2 id="Syntax">Syntax</h2> + +<pre class="syntaxbox"><em>var intervalID</em> = <em>scope</em>.setInterval(<em>func</em>, [<em>delay</em>, <em>arg1</em>, <em>arg2</em>, ...]); +<em>var intervalID</em> = <em>scope</em>.setInterval(<em>code</em>, [<em>delay]</em>); +</pre> + +<h3 id="Parameters">Parameters</h3> + +<dl> + <dt><code>func</code></dt> + <dd>A {{jsxref("function")}} to be executed every <code>delay</code> milliseconds. The function is not passed any arguments, and no return value is expected.</dd> + <dt><code>code</code></dt> + <dd>An optional syntax allows you to include a string instead of a function, which is compiled and executed every <code>delay</code> milliseconds. This syntax is <em>not recommended</em> for the same reasons that make using {{jsxref("eval", "eval()")}} a security risk.</dd> + <dt><code>delay</code>{{optional_inline}}</dt> + <dd>The time, in milliseconds (thousandths of a second), the timer should delay in between executions of the specified function or code. See {{anch("Delay restrictions")}} below for details on the permitted range of <code>delay</code> values.</dd> + <dt><code>arg1, ..., argN</code> {{optional_inline}}</dt> + <dd>Additional arguments which are passed through to the function specified by <em>func</em> once the timer expires.</dd> +</dl> + +<div class="note"> +<p><strong>Note</strong>: Passing additional arguments to <code>setInterval()</code> in the first syntax does not work in Internet Explorer 9 and earlier. If you want to enable this functionality on that browser, you must use a polyfill (see the <a href="#Callback_arguments">Callback arguments</a> section).</p> +</div> + +<h3 id="Return_value">Return value</h3> + +<p>The returned <code>intervalID</code> is a numeric, non-zero value which identifies the timer created by the call to <code>setInterval()</code>; this value can be passed to {{domxref("WindowOrWorkerGlobalScope.clearInterval()")}} to cancel the timeout.</p> + +<p>It may be helpful to be aware that <code>setInterval()</code> and {{domxref("WindowOrWorkerGlobalScope.setTimeout", "setTimeout()")}} share the same pool of IDs, and that <code>clearInterval()</code> and {{domxref("WindowOrWorkerGlobalScope.clearTimeout", "clearTimeout()")}} can technically be used interchangeably. For clarity, however, you should try to always match them to avoid confusion when maintaining your code.</p> + +<div class="note"><strong>Note</strong>: The <code>delay</code> argument is converted to a signed 32-bit integer. This effectively limits <code>delay</code> to 2147483647 ms, since it's specified as a signed integer in the IDL.</div> + +<h2 id="Examples">Examples</h2> + +<h3 id="Example_1_Basic_syntax">Example 1: Basic syntax</h3> + +<p>The following example demonstrates <code>setInterval()</code>'s basic syntax.</p> + +<pre class="brush:js">var intervalID = window.setInterval(myCallback, 500, 'Parameter 1', 'Parameter 2'); + +function myCallback(a, b) +{ + // Your code here + // Parameters are purely optional. + console.log(a); + console.log(b); +} +</pre> + +<h3 id="Example_2_Alternating_two_colors">Example 2: Alternating two colors</h3> + +<p>The following example calls the <code>flashtext()</code> function once a second until the Stop button is pressed.</p> + +<pre class="brush:html"><!DOCTYPE html> +<html> +<head> + <meta charset="UTF-8" /> + <title>setInterval/clearInterval example</title> + + <script> + var nIntervId; + + function changeColor() { + nIntervId = setInterval(flashText, 1000); + } + + function flashText() { + var oElem = document.getElementById('my_box'); + oElem.style.color = oElem.style.color == 'red' ? 'blue' : 'red'; + // oElem.style.color == 'red' ? 'blue' : 'red' is a ternary operator. + } + + function stopTextColor() { + clearInterval(nIntervId); + } + </script> +</head> + +<body onload="changeColor();"> + <div id="my_box"> + <p>Hello World</p> + </div> + + <button onclick="stopTextColor();">Stop</button> +</body> +</html> +</pre> + +<h3 id="Example_3_Typewriter_simulation">Example 3: Typewriter simulation</h3> + +<p>The following example simulates typewriter by first clearing and then slowly typing content into the <a href="/en-US/docs/DOM/NodeList"><code>NodeList</code></a> that matches a specified group of selectors.</p> + +<pre class="brush:html"><!DOCTYPE html> +<html> +<head> +<meta charset="UTF-8" /> +<title>JavaScript Typewriter - MDN Example</title> +<script> + function Typewriter (sSelector, nRate) { + + function clean () { + clearInterval(nIntervId); + bTyping = false; + bStart = true; + oCurrent = null; + aSheets.length = nIdx = 0; + } + + function scroll (oSheet, nPos, bEraseAndStop) { + if (!oSheet.hasOwnProperty('parts') || aMap.length < nPos) { return true; } + + var oRel, bExit = false; + + if (aMap.length === nPos) { aMap.push(0); } + + while (aMap[nPos] < oSheet.parts.length) { + oRel = oSheet.parts[aMap[nPos]]; + + scroll(oRel, nPos + 1, bEraseAndStop) ? aMap[nPos]++ : bExit = true; + + if (bEraseAndStop && (oRel.ref.nodeType - 1 | 1) === 3 && oRel.ref.nodeValue) { + bExit = true; + oCurrent = oRel.ref; + sPart = oCurrent.nodeValue; + oCurrent.nodeValue = ''; + } + + oSheet.ref.appendChild(oRel.ref); + if (bExit) { return false; } + } + + aMap.length--; + return true; + } + + function typewrite () { + if (sPart.length === 0 && scroll(aSheets[nIdx], 0, true) && nIdx++ === aSheets.length - 1) { clean(); return; } + + oCurrent.nodeValue += sPart.charAt(0); + sPart = sPart.slice(1); + } + + function Sheet (oNode) { + this.ref = oNode; + if (!oNode.hasChildNodes()) { return; } + this.parts = Array.prototype.slice.call(oNode.childNodes); + + for (var nChild = 0; nChild < this.parts.length; nChild++) { + oNode.removeChild(this.parts[nChild]); + this.parts[nChild] = new Sheet(this.parts[nChild]); + } + } + + var + nIntervId, oCurrent = null, bTyping = false, bStart = true, + nIdx = 0, sPart = "", aSheets = [], aMap = []; + + this.rate = nRate || 100; + + this.play = function () { + if (bTyping) { return; } + if (bStart) { + var aItems = document.querySelectorAll(sSelector); + + if (aItems.length === 0) { return; } + for (var nItem = 0; nItem < aItems.length; nItem++) { + aSheets.push(new Sheet(aItems[nItem])); + /* Uncomment the following line if you have previously hidden your elements via CSS: */ + // aItems[nItem].style.visibility = "visible"; + } + + bStart = false; + } + + nIntervId = setInterval(typewrite, this.rate); + bTyping = true; + }; + + this.pause = function () { + clearInterval(nIntervId); + bTyping = false; + }; + + this.terminate = function () { + oCurrent.nodeValue += sPart; + sPart = ""; + for (nIdx; nIdx < aSheets.length; scroll(aSheets[nIdx++], 0, false)); + clean(); + }; +} + +/* usage: */ +var oTWExample1 = new Typewriter(/* elements: */ '#article, h1, #info, #copyleft', /* frame rate (optional): */ 15); + +/* default frame rate is 100: */ +var oTWExample2 = new Typewriter('#controls'); + +/* you can also change the frame rate value modifying the "rate" property; for example: */ +// oTWExample2.rate = 150; + +onload = function () { + oTWExample1.play(); + oTWExample2.play(); +}; +</script> +<style type="text/css"> +span.intLink, a, a:visited { + cursor: pointer; + color: #000000; + text-decoration: underline; +} + +#info { + width: 180px; + height: 150px; + float: right; + background-color: #eeeeff; + padding: 4px; + overflow: auto; + font-size: 12px; + margin: 4px; + border-radius: 5px; + /* visibility: hidden; */ +} +</style> +</head> + +<body> + +<p id="copyleft" style="font-style: italic; font-size: 12px; text-align: center;">CopyLeft 2012 by <a href="https://developer.mozilla.org/" target="_blank">Mozilla Developer Network</a></p> +<p id="controls" style="text-align: center;">[&nbsp;<span class="intLink" onclick="oTWExample1.play();">Play</span> | <span class="intLink" onclick="oTWExample1.pause();">Pause</span> | <span class="intLink" onclick="oTWExample1.terminate();">Terminate</span>&nbsp;]</p> +<div id="info"> +Vivamus blandit massa ut metus mattis in fringilla lectus imperdiet. Proin ac ante a felis ornare vehicula. Fusce pellentesque lacus vitae eros convallis ut mollis magna pellentesque. Pellentesque placerat enim at lacus ultricies vitae facilisis nisi fringilla. In tincidunt tincidunt tincidunt. +</div> +<h1>JavaScript Typewriter</h1> + +<div id="article"> +<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam ultrices dolor ac dolor imperdiet ullamcorper. Suspendisse quam libero, luctus auctor mollis sed, malesuada condimentum magna. Quisque in ante tellus, in placerat est. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Donec a mi magna, quis mattis dolor. Etiam sit amet ligula quis urna auctor imperdiet nec faucibus ante. Mauris vel consectetur dolor. Nunc eget elit eget velit pulvinar fringilla consectetur aliquam purus. Curabitur convallis, justo posuere porta egestas, velit erat ornare tortor, non viverra justo diam eget arcu. Phasellus adipiscing fermentum nibh ac commodo. Nam turpis nunc, suscipit a hendrerit vitae, volutpat non ipsum.</p> +<form> +<p>Phasellus ac nisl lorem: <input type="text" /><br /> +<textarea style="width: 400px; height: 200px;">Nullam commodo suscipit lacus non aliquet. Phasellus ac nisl lorem, sed facilisis ligula. Nam cursus lobortis placerat. Sed dui nisi, elementum eu sodales ac, placerat sit amet mauris. Pellentesque dapibus tellus ut ipsum aliquam eu auctor dui vehicula. Quisque ultrices laoreet erat, at ultrices tortor sodales non. Sed venenatis luctus magna, ultricies ultricies nunc fringilla eget. Praesent scelerisque urna vitae nibh tristique varius consequat neque luctus. Integer ornare, erat a porta tempus, velit justo fermentum elit, a fermentum metus nisi eu ipsum. Vivamus eget augue vel dui viverra adipiscing congue ut massa. Praesent vitae eros erat, pulvinar laoreet magna. Maecenas vestibulum mollis nunc in posuere. Pellentesque sit amet metus a turpis lobortis tempor eu vel tortor. Cras sodales eleifend interdum.</textarea></p> +<p><input type="submit" value="Send" /> +</form> +<p>Duis lobortis sapien quis nisl luctus porttitor. In tempor semper libero, eu tincidunt dolor eleifend sit amet. Ut nec velit in dolor tincidunt rhoncus non non diam. Morbi auctor ornare orci, non euismod felis gravida nec. Curabitur elementum nisi a eros rutrum nec blandit diam placerat. Aenean tincidunt risus ut nisi consectetur cursus. Ut vitae quam elit. Donec dignissim est in quam tempor consequat. Aliquam aliquam diam non felis convallis suscipit. Nulla facilisi. Donec lacus risus, dignissim et fringilla et, egestas vel eros. Duis malesuada accumsan dui, at fringilla mauris bibStartum quis. Cras adipiscing ultricies fermentum. Praesent bibStartum condimentum feugiat.</p> +<p>Nam faucibus, ligula eu fringilla pulvinar, lectus tellus iaculis nunc, vitae scelerisque metus leo non metus. Proin mattis lobortis lobortis. Quisque accumsan faucibus erat, vel varius tortor ultricies ac. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nec libero nunc. Nullam tortor nunc, elementum a consectetur et, ultrices eu orci. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque a nisl eu sem vehicula egestas.</p> +</div> +</body> +</html></pre> + +<p><a href="/files/3997/typewriter.html">View this demo in action</a>. See also: <a href="/en-US/docs/DOM/window.clearInterval"><code>clearInterval()</code></a>.</p> + +<h2 id="Callback_arguments">Callback arguments</h2> + +<p>As previously discussed, Internet Explorer versions 9 and below do not support the passing of arguments to the callback function in either <code>setTimeout()</code> or <code>setInterval()</code>. The following <strong>IE-specific</strong> code demonstrates a method for overcoming this limitation. To use, simply add the following code to the top of your script.</p> + +<pre class="brush:js">/*\ +|*| +|*| IE-specific polyfill that enables the passage of arbitrary arguments to the +|*| callback functions of javascript timers (HTML5 standard syntax). +|*| +|*| https://developer.mozilla.org/en-US/docs/Web/API/window.setInterval +|*| https://developer.mozilla.org/User:fusionchess +|*| +|*| Syntax: +|*| var timeoutID = window.setTimeout(func, delay[, arg1, arg2, ...]); +|*| var timeoutID = window.setTimeout(code, delay); +|*| var intervalID = window.setInterval(func, delay[, arg1, arg2, ...]); +|*| var intervalID = window.setInterval(code, delay); +|*| +\*/ + +if (document.all && !window.setTimeout.isPolyfill) { + var __nativeST__ = window.setTimeout; + window.setTimeout = function (vCallback, nDelay /*, argumentToPass1, argumentToPass2, etc. */) { + var aArgs = Array.prototype.slice.call(arguments, 2); + return __nativeST__(vCallback instanceof Function ? function () { + vCallback.apply(null, aArgs); + } : vCallback, nDelay); + }; + window.setTimeout.isPolyfill = true; +} + +if (document.all && !window.setInterval.isPolyfill) { + var __nativeSI__ = window.setInterval; + window.setInterval = function (vCallback, nDelay /*, argumentToPass1, argumentToPass2, etc. */) { + var aArgs = Array.prototype.slice.call(arguments, 2); + return __nativeSI__(vCallback instanceof Function ? function () { + vCallback.apply(null, aArgs); + } : vCallback, nDelay); + }; + window.setInterval.isPolyfill = true; +} +</pre> + +<p>Another possibility is to use an anonymous function to call your callback, although this solution is a bit more expensive. Example:</p> + +<pre class="brush:js">var intervalID = setInterval(function() { myFunc('one', 'two', 'three'); }, 1000);</pre> + +<p>Another possibility is to use <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/bind">function's bind</a>. Example:</p> + +<pre class="brush:js">var intervalID = setInterval(function(arg1) {}.bind(undefined, 10), 1000);</pre> + +<p>{{h3_gecko_minversion("Inactive tabs", "5.0")}}</p> + +<p>Starting in Gecko 5.0 {{geckoRelease("5.0")}}, intervals are clamped to fire no more often than once per second in inactive tabs.</p> + +<h2 id="The_this_problem">The "<a href="/en-US/docs/Web/JavaScript/Reference/Operators/this"><code>this</code></a>" problem</h2> + +<p>When you pass a method to <code>setInterval()</code> or any other function, it is invoked with the wrong <a href="/en-US/docs/Web/JavaScript/Reference/Operators/this"><code>this</code></a> value. This problem is explained in detail in the <a href="/en-US/docs/Web/JavaScript/Reference/Operators/this#As_an_object_method">JavaScript reference</a>.</p> + +<h3 id="Explanation">Explanation</h3> + +<p>Code executed by <code>setInterval()</code> runs in a separate execution context than the function from which it was called. As a consequence, the <a href="/en-US/docs/Web/JavaScript/Reference/Operators/this"><code>this</code></a> keyword for the called function is set to the <code>window</code> (or <code>global</code>) object, it is not the same as the <code>this</code> value for the function that called <code>setTimeout</code>. See the following example (which uses <code>setTimeout()</code> instead of <code>setInterval()</code> – the problem, in fact, is the same for both timers):</p> + +<pre class="brush:js">myArray = ['zero', 'one', 'two']; + +myArray.myMethod = function (sProperty) { + alert(arguments.length > 0 ? this[sProperty] : this); +}; + +myArray.myMethod(); // prints "zero,one,two" +myArray.myMethod(1); // prints "one" +setTimeout(myArray.myMethod, 1000); // prints "[object Window]" after 1 second +setTimeout(myArray.myMethod, 1500, "1"); // prints "undefined" after 1,5 seconds +// passing the 'this' object with .call won't work +// because this will change the value of this inside setTimeout itself +// while we want to change the value of this inside myArray.myMethod +// in fact, it will be an error because setTimeout code expects this to be the window object: +setTimeout.call(myArray, myArray.myMethod, 2000); // error: "NS_ERROR_XPC_BAD_OP_ON_WN_PROTO: Illegal operation on WrappedNative prototype object" +setTimeout.call(myArray, myArray.myMethod, 2500, 2); // same error +</pre> + +<p>As you can see there are no ways to pass the <code>this</code> object to the callback function in the legacy JavaScript.</p> + +<h3 id="A_possible_solution">A possible solution</h3> + +<p>A possible way to solve the "<code>this</code>" problem is to replace the two native <code>setTimeout()</code> or <code>setInterval()</code> global functions with two <em>non-native</em> ones that enable their invocation through the <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Function/call"><code>Function.prototype.call</code></a> method. The following example shows a possible replacement:</p> + +<pre class="brush:js">// Enable the passage of the 'this' object through the JavaScript timers + +var __nativeST__ = window.setTimeout, __nativeSI__ = window.setInterval; + +window.setTimeout = function (vCallback, nDelay /*, argumentToPass1, argumentToPass2, etc. */) { + var oThis = this, aArgs = Array.prototype.slice.call(arguments, 2); + return __nativeST__(vCallback instanceof Function ? function () { + vCallback.apply(oThis, aArgs); + } : vCallback, nDelay); +}; + +window.setInterval = function (vCallback, nDelay /*, argumentToPass1, argumentToPass2, etc. */) { + var oThis = this, aArgs = Array.prototype.slice.call(arguments, 2); + return __nativeSI__(vCallback instanceof Function ? function () { + vCallback.apply(oThis, aArgs); + } : vCallback, nDelay); +};</pre> + +<div class="note">These two replacements also enable the HTML5 standard passage of arbitrary arguments to the callback functions of timers in IE. So they can be used as <em>non-standard-compliant</em> polyfills also. See the <a href="#Callback_arguments">callback arguments paragraph</a> for a <em>standard-compliant</em> polyfill.</div> + +<p>New feature test:</p> + +<pre class="brush:js">myArray = ['zero', 'one', 'two']; + +myArray.myMethod = function (sProperty) { + alert(arguments.length > 0 ? this[sProperty] : this); +}; + +setTimeout(alert, 1500, 'Hello world!'); // the standard use of setTimeout and setInterval is preserved, but... +setTimeout.call(myArray, myArray.myMethod, 2000); // prints "zero,one,two" after 2 seconds +setTimeout.call(myArray, myArray.myMethod, 2500, 2); // prints "two" after 2,5 seconds +</pre> + +<p>Another, more complex, solution for<strong> </strong>the <a href="/en-US/docs/Web/JavaScript/Reference/Operators/this"><code>this</code></a> problem<strong> </strong>is <a href="#MiniDaemon_-_A_framework_for_managing_timers">the following framework</a>.</p> + +<div class="note">JavaScript 1.8.5 introduces the <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/bind">Function.prototype.bind()</a></code> method, which lets you specify the value that should be used as <code>this</code> for all calls to a given function. This lets you easily bypass problems where it's unclear what this will be, depending on the context from which your function was called. Also, ES2015 supports <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions">arrow functions</a>, with lexical this allowing us to write setInterval( () => this.myMethod) if we're inside myArray method.</div> + +<h2 id="MiniDaemon_-_A_framework_for_managing_timers">MiniDaemon - A framework for managing timers</h2> + +<p>In pages requiring many timers, it can often be difficult to keep track of all of the running timer events. One approach to solving this problem is to store information about the state of a timer in an object. Following is a minimal example of such an abstraction. The constructor architecture explicitly avoids the use of closures. It also offers an alternative way to pass the <a href="/en-US/docs/Web/JavaScript/Reference/Operators/this"><code>this</code></a> object to the callback function (see <a href="#The_.22this.22_problem">The "this" problem</a> for details). The following code is also <a href="https://github.com/madmurphy/minidaemon.js">available on GitHub</a>.</p> + +<div class="note">For a more complex but still modular version of it (<code><em>Daemon</em></code>) see <a href="/en-US/Add-ons/Code_snippets/Timers/Daemons">JavaScript Daemons Management</a>. This more complex version is nothing but a big and scalable collection of methods for the <code><em>Daemon</em></code> constructor. However, the <code><em>Daemon</em></code> constructor itself is nothing but a clone of <code><em>MiniDaemon</em></code> with an added support for <em>init</em> and <em>onstart</em> functions declarable during the instantiation of the <code><em>daemon</em></code>. <strong>So the <code><em>MiniDaemon</em></code> framework remains the recommended way for simple animations</strong>, because <code><em>Daemon</em></code> without its collection of methods is essentially a clone of it.</div> + +<h3 id="minidaemon.js">minidaemon.js</h3> + +<pre class="brush:js">/*\ +|*| +|*| :: MiniDaemon :: +|*| +|*| Revision #2 - September 26, 2014 +|*| +|*| https://developer.mozilla.org/en-US/docs/Web/API/window.setInterval +|*| https://developer.mozilla.org/User:fusionchess +|*| https://github.com/madmurphy/minidaemon.js +|*| +|*| This framework is released under the GNU Lesser General Public License, version 3 or later. +|*| http://www.gnu.org/licenses/lgpl-3.0.html +|*| +\*/ + +function MiniDaemon (oOwner, fTask, nRate, nLen) { + if (!(this && this instanceof MiniDaemon)) { return; } + if (arguments.length < 2) { throw new TypeError('MiniDaemon - not enough arguments'); } + if (oOwner) { this.owner = oOwner; } + this.task = fTask; + if (isFinite(nRate) && nRate > 0) { this.rate = Math.floor(nRate); } + if (nLen > 0) { this.length = Math.floor(nLen); } +} + +MiniDaemon.prototype.owner = null; +MiniDaemon.prototype.task = null; +MiniDaemon.prototype.rate = 100; +MiniDaemon.prototype.length = Infinity; + + /* These properties should be read-only */ + +MiniDaemon.prototype.SESSION = -1; +MiniDaemon.prototype.INDEX = 0; +MiniDaemon.prototype.PAUSED = true; +MiniDaemon.prototype.BACKW = true; + + /* Global methods */ + +MiniDaemon.forceCall = function (oDmn) { + oDmn.INDEX += oDmn.BACKW ? -1 : 1; + if (oDmn.task.call(oDmn.owner, oDmn.INDEX, oDmn.length, oDmn.BACKW) === false || oDmn.isAtEnd()) { oDmn.pause(); return false; } + return true; +}; + + /* Instances methods */ + +MiniDaemon.prototype.isAtEnd = function () { + return this.BACKW ? isFinite(this.length) && this.INDEX < 1 : this.INDEX + 1 > this.length; +}; + +MiniDaemon.prototype.synchronize = function () { + if (this.PAUSED) { return; } + clearInterval(this.SESSION); + this.SESSION = setInterval(MiniDaemon.forceCall, this.rate, this); +}; + +MiniDaemon.prototype.pause = function () { + clearInterval(this.SESSION); + this.PAUSED = true; +}; + +MiniDaemon.prototype.start = function (bReverse) { + var bBackw = Boolean(bReverse); + if (this.BACKW === bBackw && (this.isAtEnd() || !this.PAUSED)) { return; } + this.BACKW = bBackw; + this.PAUSED = false; + this.synchronize(); +}; +</pre> + +<div class="note">MiniDaemon passes arguments to the callback function. If you want to work on it with browsers that natively do not support this feature, use one of the methods proposed above.</div> + +<h3 id="Syntax_2">Syntax</h3> + +<p><code>var myDaemon = new MiniDaemon(<em>thisObject</em>, <em>callback</em>[</code><code>, <em>rate</em></code><code>[, <em>length</em>]]);</code></p> + +<h3 id="Description">Description</h3> + +<p>Returns a JavaScript <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object"><code>Object</code></a> containing all information needed by an animation (like the <a href="/en-US/docs/Web/JavaScript/Reference/Operators/this"><code>this</code></a> object, the callback function, the length, the frame-rate).</p> + +<h4 id="Arguments">Arguments</h4> + +<dl> + <dt><code>thisObject</code></dt> + <dd>The <a href="/en-US/docs/Web/JavaScript/Reference/Operators/this"><code>this</code></a> object on which the <em>callback</em> function is called. It can be an <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object"><code>object</code></a> or <code>null</code>.</dd> + <dt><code>callback</code></dt> + <dd>The function that is repeatedly invoked . <strong>It is called with three arguments</strong>: <em>index</em> (the iterative index of each invocation), <em>length</em> (the number of total invocations assigned to the <em>daemon</em> - finite or <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Infinity"><code>Infinity</code></a>) and <em>backwards</em> (a boolean expressing whether the <em>index</em> is increasing or decreasing). It is something like <em>callback</em>.call(<em>thisObject</em>, <em>index</em>, <em>length</em>, <em>backwards</em>). <strong>If the callback function returns a <code>false</code> value the <em>daemon</em> is paused</strong>.</dd> + <dt><code>rate (optional)</code></dt> + <dd>The time lapse (in number of milliseconds) between each invocation. The default value is 100.</dd> + <dt><code>length (optional)</code></dt> + <dd>The total number of invocations. It can be a positive integer or <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity"><code>Infinity</code></a>. The default value is <code>Infinity</code>.</dd> +</dl> + +<h4 id="MiniDaemon_instances_properties"><code>MiniDaemon</code> instances properties</h4> + +<dl> + <dt><code>myDaemon.owner</code></dt> + <dd>The <a href="/en-US/docs/Web/JavaScript/Reference/Operators/this"><code>this</code></a> object on which is executed the daemon (read/write). It can be an <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object"><code>object</code></a> or <code>null</code>.</dd> + <dt><code>myDaemon.task</code></dt> + <dd>The function that is repeatedly invoked (read/write). It is called with three arguments: <em>index</em> (the iterative index of each invocation), <em>length</em> (the number of total invocations assigned to the daemon - finite or <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Infinity"><code>Infinity</code></a>) and backwards (a boolean expressing whether the <em>index</em> is decreasing or not) – see above. If the <code>myDaemon.task</code> function returns a <code>false</code> value the <em>daemon</em> is paused.</dd> + <dt><code>myDaemon.rate</code></dt> + <dd>The time lapse (in number of milliseconds) between each invocation (read/write).</dd> + <dt><code>myDaemon.length</code></dt> + <dd>The total number of invocations. It can be a positive integer or <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity"><code>Infinity</code></a> (read/write).</dd> +</dl> + +<h4 id="MiniDaemon_instances_methods"><code>MiniDaemon</code> instances methods</h4> + +<dl> + <dt><code>myDaemon.isAtEnd()</code></dt> + <dd>Returns a boolean expressing whether the <em>daemon</em> is at the start/end position or not.</dd> + <dt><code>myDaemon.synchronize()</code></dt> + <dd>Synchronize the timer of a started daemon with the time of its invocation.</dd> + <dt><code>myDaemon.pause()</code></dt> + <dd>Pauses the daemon.</dd> + <dt><code>myDaemon.start([<em>reverse</em>])</code></dt> + <dd>Starts the daemon forward (<em>index</em> of each invocation increasing) or backwards (<em>index</em> decreasing).</dd> +</dl> + +<h4 id="MiniDaemon_global_object_methods"><code>MiniDaemon</code> global object methods</h4> + +<dl> + <dt><code>MiniDaemon.forceCall(<em>minidaemon</em>)</code></dt> + <dd>Forces a single callback to the <code><em>minidaemon</em>.task</code> function regardless of the fact that the end has been reached or not. In any case the internal <code>INDEX</code> property is increased/decreased (depending on the actual direction of the process).</dd> +</dl> + +<h3 id="Example_usage">Example usage</h3> + +<p>Your HTML page:</p> + +<pre class="brush:html"><!DOCTYPE html> +<html> +<head> + <meta charset="UTF-8" /> + <title>MiniDaemin Example - MDN</title> + <script type="text/javascript" src="minidaemon.js"></script> + <style type="text/css"> + #sample_div { + visibility: hidden; + } + </style> +</head> + +<body> + <p> + <input type="button" onclick="fadeInOut.start(false /* optional */);" value="fade in" /> + <input type="button" onclick="fadeInOut.start(true);" value="fade out"> + <input type="button" onclick="fadeInOut.pause();" value="pause" /> + </p> + + <div id="sample_div">Some text here</div> + + <script type="text/javascript"> + function opacity (nIndex, nLength, bBackwards) { + this.style.opacity = nIndex / nLength; + if (bBackwards ? nIndex === 0 : nIndex === 1) { + this.style.visibility = bBackwards ? 'hidden' : 'visible'; + } + } + + var fadeInOut = new MiniDaemon(document.getElementById('sample_div'), opacity, 300, 8); + </script> +</body> +</html></pre> + +<p><a href="/files/3995/minidaemon_example.html" title="MiniDaemon Example">View this example in action</a></p> + +<h2 id="Usage_notes">Usage notes</h2> + +<p>The <code>setInterval()</code> function is commonly used to set a delay for functions that are executed again and again, such as animations. You can cancel the interval using {{domxref("WindowOrWorkerGlobalScope.clearInterval()")}}.</p> + +<p>If you wish to have your function called <em>once</em> after the specified delay, use {{domxref("WindowOrWorkerGlobalScope.setTimeout()")}}.</p> + +<h3 id="Delay_restrictions">Delay restrictions</h3> + +<p>It's possible for intervals to be nested; that is, the callback for <code>setInterval()</code> can in turn call <code>setInterval()</code> to start another interval running, even though the first one is still going. To mitigate the potential impact this can have on performance, once intervals are nested beyond five levels deep, the browser will automatically enforce a 4 ms minimum value for the interval. Attempts to specify a value less than 4 ms in deeply-nested calls to <code>setInterval()</code> will be pinned to 4 ms.</p> + +<p>Browsers may enforce even more stringent minimum values for the interval under some circumstances, although these should not be common. Note also that the actual amount of time that elapses between calls to the callback may be longer than the given <code>delay</code>; see {{SectionOnPage("/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout", "Reasons for delays longer than specified")}} for examples.</p> + +<h3 id="Ensure_that_execution_duration_is_shorter_than_interval_frequency">Ensure that execution duration is shorter than interval frequency</h3> + +<p>If there is a possibility that your logic could take longer to execute than the interval time, it is recommended that you recursively call a named function using {{domxref("WindowOrWorkerGlobalScope.setTimeout", "setTimeout()")}}. For example, if using <code>setInterval()</code> to poll a remote server every 5 seconds, network latency, an unresponsive server, and a host of other issues could prevent the request from completing in its allotted time. As such, you may find yourself with queued up XHR requests that won't necessarily return in order.</p> + +<p>In these cases, a recursive <code>setTimeout()</code> pattern is preferred:</p> + +<pre class="brush:js">(function loop(){ + setTimeout(function() { + // Your logic here + + loop(); + }, delay); +})(); +</pre> + +<p>In the above snippet, a named function <code>loop()</code> is declared and is immediately executed. <code>loop()</code> is recursively called inside <code>setTimeout()</code> after the logic has completed executing. While this pattern does not guarantee execution on a fixed interval, it does guarantee that the previous interval has completed before recursing.</p> + +<h2 id="Specifications">Specifications</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th>Specification</th> + <th>Status</th> + <th>Comment</th> + </tr> + <tr> + <td>{{SpecName('HTML WHATWG', 'webappapis.html#dom-setinterval', 'WindowOrWorkerGlobalScope.setInterval()')}}</td> + <td>{{Spec2("HTML WHATWG")}}</td> + <td>Method moved to the <code>WindowOrWorkerGlobalScope</code> mixin in the latest spec.</td> + </tr> + <tr> + <td>{{SpecName("HTML WHATWG", "webappapis.html#dom-setinterval", "WindowTimers.setInterval()")}}</td> + <td>{{Spec2("HTML WHATWG")}}</td> + <td>Initial definition (DOM Level 0)</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<div> + + +<p>{{Compat("api.WindowOrWorkerGlobalScope.setInterval")}}</p> +</div> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/Add-ons/Code_snippets/Timers">JavaScript timers</a></li> + <li>{{domxref("WindowOrWorkerGlobalScope.setTimeout")}}</li> + <li>{{domxref("WindowOrWorkerGlobalScope.clearTimeout")}}</li> + <li>{{domxref("WindowOrWorkerGlobalScope.clearInterval")}}</li> + <li>{{domxref("window.requestAnimationFrame")}}</li> + <li><a href="/en-US/Add-ons/Code_snippets/Timers/Daemons"><em>Daemons</em> management</a></li> +</ul> diff --git a/files/zh-tw/web/api/windowtimers/index.html b/files/zh-tw/web/api/windowtimers/index.html new file mode 100644 index 0000000000..0b26118e10 --- /dev/null +++ b/files/zh-tw/web/api/windowtimers/index.html @@ -0,0 +1,114 @@ +--- +title: WindowTimers +slug: Web/API/WindowTimers +translation_of: Web/API/WindowOrWorkerGlobalScope +--- +<div>{{APIRef("HTML DOM")}}</div> + +<p><code><strong>WindowTimers</strong></code> is a mixin used to provide utility methods which set and clear timers. No objects of this type exist; instead, its methods are available on {{domxref("Window")}} for the standard browsing scope, or on {{domxref("WorkerGlobalScope")}} for workers.</p> + +<h2 id="屬性">屬性</h2> + +<p><em>WindowTimers 介面沒有繼承也沒有定義任何屬性。</em></p> + +<h2 id="方法">方法</h2> + +<p><em>除以下自身方法外，WindowTimers 介面提沒有任何繼承方法。</em></p> + +<dl> + <dt>{{domxref("WindowTimers.clearInterval()")}}</dt> + <dd>Cancels the repeated execution set using {{domxref("WindowTimers.setInterval()")}}.</dd> + <dt>{{domxref("WindowTimers.clearTimeout()")}}</dt> + <dd>Cancels the delayed execution set using {{domxref("WindowTimers.setTimeout()")}}.</dd> + <dt>{{domxref("WindowTimers.setInterval()")}}</dt> + <dd>Schedules a function to execute every time a given number of milliseconds elapses.</dd> + <dt>{{domxref("WindowTimers.setTimeout()")}}</dt> + <dd>Schedules a function to execute in a given amount of time.</dd> +</dl> + +<h2 id="規範">規範</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', '#windowtimers', 'WindowTimers')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>No change since the latest snapshot, {{SpecName("HTML5.1")}}.</td> + </tr> + <tr> + <td>{{SpecName('HTML5.1', '#windowtimers', 'WindowTimers')}}</td> + <td>{{Spec2('HTML5.1')}}</td> + <td>Snapshot of {{SpecName("HTML WHATWG")}}. No change.</td> + </tr> + <tr> + <td>{{SpecName("HTML5 W3C", "#windowtimers", "WindowTimers")}}</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="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Firefox (Gecko)</th> + <th>Chrome</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatGeckoDesktop(1)}}</td> + <td>1.0</td> + <td>4.0</td> + <td>4.0</td> + <td>1.0</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Firefox Mobile (Gecko)</th> + <th>Android</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatGeckoMobile(1)}}</td> + <td rowspan="1">{{CompatVersionUnknown}}</td> + <td rowspan="1">{{CompatVersionUnknown}}</td> + <td rowspan="1">{{CompatVersionUnknown}}</td> + <td rowspan="1">{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p> </p> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("Window")}}, {{domxref("WorkerGlobalScope")}}, {{domxref("DedicatedWorkerGlobalScope")}}, {{domxref("SharedWorkerGlobalScope")}}, and {{domxref("ServiceWorkerGlobalScope")}}</li> +</ul> diff --git a/files/zh-tw/web/api/xmlhttprequest/index.html b/files/zh-tw/web/api/xmlhttprequest/index.html new file mode 100644 index 0000000000..3258579e62 --- /dev/null +++ b/files/zh-tw/web/api/xmlhttprequest/index.html @@ -0,0 +1,177 @@ +--- +title: XMLHttpRequest +slug: Web/API/XMLHttpRequest +tags: + - AJAX + - Fixit + - HTTP + - MakeBrowserAgnostic + - NeedsCleanup + - NeedsMobileBrowserCompatibility + - NeedsTranslation + - TopicStub + - XMLHttpRequest +translation_of: Web/API/XMLHttpRequest +--- +<div>{{DefaultAPISidebar("XMLHttpRequest")}}</div> + +<p><span class="seoSummary">藉由 <code>XMLHttpRequest</code>（XHR）物件的方式來存取伺服器端的資料，可以讓你直接經由指定的 URL 擷取資料卻不用刷新整個網頁。這樣一來當想要更新網頁中的部分資料時，不再需要藉由刷新整個頁面的方法而中斷使用者的操作。在</span>{{Glossary("AJAX")}}應用中 <code>XMLHttpRequest</code> 被大量的使用。</p> + +<p>{{InheritanceDiagram(650, 150)}}</p> + +<p>雖然 <span class="seoSummary"><code>XMLHttpRequest</code></span> 這個物件的命名包含了 XML 與 HTTP 等字眼，但實際上 <code>XMLHttpRequest</code> 可用來接收任何類型的資料，不限於 XML 類型而已。</p> + +<p>如果在資料交換的時候，需要接收從伺服器端傳來的事件或訊息：可以考慮透過{{domxref("EventSource")}}介面使用<a href="/zh-TW/docs/Web/API/Server-sent_events">server-sent 事件</a>。對於和伺服器全雙工的資訊交換，<a href="/en-US/docs/Web/API/WebSockets_API">WebSockets</a> 可能是較佳的選擇。</p> + +<h2 id="建構式">建構式</h2> + +<dl> + <dt>{{domxref("XMLHttpRequest.XMLHttpRequest", "XMLHttpRequest()")}}</dt> + <dd>建構式用來初始化一個 <code>XMLHttpRequest</code> 物件。必須在其他任何所屬方法被呼叫之前被呼叫。</dd> +</dl> + +<h2 id="屬性">屬性</h2> + +<p><em>此介面也繼承了 {{domxref("XMLHttpRequestEventTarget")}} 及 {{domxref("EventTarget")}} 的屬性。</em></p> + +<dl> + <dt id="xmlhttprequest-onreadystatechange">{{domxref("XMLHttpRequest.onreadystatechange")}}</dt> + <dd>一個 {{domxref("EventHandler")}}（事件處理器）函式，會於 <code>readyState</code> 屬性之狀態改變時被呼叫。</dd> + <dt id="xmlhttprequest-readystate">{{domxref("XMLHttpRequest.readyState")}} {{readonlyinline}}</dt> + <dd>回傳一個無符號短整數（<code>unsigned short</code>）代表請求之狀態。</dd> + <dt>{{domxref("XMLHttpRequest.response")}} {{readonlyinline}}</dt> + <dd>回傳的內容可能是 {{domxref("ArrayBuffer")}}、{{domxref("Blob")}}、{{domxref("Document")}}、JavaScript 物件或 {{domxref("DOMString")}}。完全根據 {{domxref("XMLHttpRequest.responseType")}} 的值決定回傳的內容為何種型態，資料為回應實體中的內容（response entity body）。</dd> + <dt id="xmlhttprequest-responsetext">{{domxref("XMLHttpRequest.responseText")}} {{readonlyinline}}</dt> + <dd>回傳一個 {{domxref("DOMString")}}，其內容為請求之回應的文字內容。如請求失敗或尚未發送，則為 <code>null</code>。</dd> + <dt id="xmlhttprequest-responsetype">{{domxref("XMLHttpRequest.responseType")}}</dt> + <dd>為一可列舉（enumerated）值，定義回應內容的資料類型（response type）。</dd> + <dt id="xmlhttprequest-responsexml">{{domxref("XMLHttpRequest.responseURL")}} {{readonlyinline}}</dt> + <dd>回傳一個回應（response）的序列化 URL，如 URL 為 null 則回傳空字串。</dd> + <dt id="xmlhttprequest-responsexml">{{domxref("XMLHttpRequest.responseXML")}} {{readonlyinline}}</dt> + <dd>回傳一個 {{domxref("Document")}}，其內容為請求之回應內容所解析成的文件物件。如請求失敗或尚未發送，又或是無法解析成 XML、HTML，則為 <code>null</code>。Not available in workers.</dd> + <dt id="xmlhttprequest-status">{{domxref("XMLHttpRequest.status")}} {{readonlyinline}}</dt> + <dd>回傳一個無符號短整數（<code>unsigned short</code>）表示已發送請求之回應的狀態。</dd> + <dt id="xmlhttprequest-statustext">{{domxref("XMLHttpRequest.statusText")}} {{readonlyinline}}</dt> + <dd>回傳一個 {{domxref("DOMString")}} 表示 HTTP 伺服器回應之字串。和 {{domxref("XMLHTTPRequest.status")}} 不同的是，<code>XMLHttpRequest.statusText</code> 包含了回應的整個文字訊息（如 "<code>200 OK</code>"）。</dd> +</dl> + +<div class="note"> +<p><strong>Note:</strong> The HTTP/2 specification (<a href="https://http2.github.io/http2-spec/#rfc.section.8.1.2.4">8.1.2.4</a> <a href="https://http2.github.io/http2-spec/#HttpResponse">Response Pseudo-Header Fields</a>), HTTP/2 does not define a way to carry the version or reason phrase that is included in an HTTP/1.1 status line.</p> +</div> + +<dl> + <dt id="xmlhttprequest-timeout">{{domxref("XMLHttpRequest.timeout")}}</dt> + <dd>為一無符號長整數（<code>unsigned long</code>），代表一個請求在逾時而被自動中止前的可等待時間（毫秒）。</dd> + <dt id="xmlhttprequesteventtarget-ontimeout">{{domxref("XMLHttpRequestEventTarget.ontimeout")}}</dt> + <dd>為一 {{domxref("EventHandler")}} 物件，會於請求逾時時被呼叫。{{gecko_minversion_inline("12.0")}}</dd> + <dt id="xmlhttprequest-upload">{{domxref("XMLHttpRequest.upload")}} {{readonlyinline}}</dt> + <dd>為一 {{domxref("XMLHttpRequestUpload")}} 物件，代表上傳的進度。</dd> + <dt id="xmlhttprequest-withcredentials">{{domxref("XMLHttpRequest.withCredentials")}}</dt> + <dd>{{domxref("Boolean","布林值")}}。表示是否允許在跨站存取（cross-site <code>Access-Control</code>）之請求當中，發送如 cookies 或 authorization headers 等憑證資訊（credentials）。</dd> +</dl> + +<h3 id="非標準屬性">非標準屬性</h3> + +<dl> + <dt>{{domxref("XMLHttpRequest.channel")}}{{ReadOnlyInline}}</dt> + <dd>是一個 {{Interface("nsIChannel")}}。當執行要求時，物件使用的頻道（Channel）。</dd> + <dt>{{domxref("XMLHttpRequest.mozAnon")}}{{ReadOnlyInline}}</dt> + <dd>為一個布林值。如果為真，請求就會以沒有cookie及authentication headers的方式送出。</dd> + <dt>{{domxref("XMLHttpRequest.mozSystem")}}{{ReadOnlyInline}}</dt> + <dd>這是一個布林值。If true, the same origin policy will not be enforced on the request.</dd> + <dt>{{domxref("XMLHttpRequest.mozBackgroundRequest")}}</dt> + <dd>這是一個布林值。指出該物件是否為一個背景型態的服務要求。</dd> + <dt>{{domxref("XMLHttpRequest.mozResponseArrayBuffer")}}{{gecko_minversion_inline("2.0")}} {{obsolete_inline("6")}} {{ReadOnlyInline}}</dt> + <dd>Is an <a href="/zh-TW/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer"><code>ArrayBuffer</code></a>. The response to the request, as a JavaScript typed array.</dd> + <dt>{{domxref("XMLHttpRequest.multipart")}}{{obsolete_inline("22")}}</dt> + <dd><strong>This Gecko-only feature, a boolean, was removed in Firefox/Gecko 22.</strong> Please use <a href="/zh-TW/docs/Web/API/Server-sent_events">Server-Sent Events</a>, <a href="/zh-TW/docs/Web/API/WebSockets_API">Web Sockets</a>, or <code>responseText</code> from progress events instead.</dd> +</dl> + +<h3 id="事件處理器">事件處理器</h3> + +<p>所有瀏覽器都支援 <code>XMLHttpRequest</code> 物件實體的 <code>onreadystatechange</code> 屬性。</p> + +<p>之後，各個瀏覽器實作了多種額外的事件處理器（如 <code>onload</code>、<code>onerror</code>、<code>onprogress</code> 等）。請參考<a href="https://developer.mozilla.org/zh-TW/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest">使用 XMLHttpRequest</a>。</p> + +<p>除了以 <code>on*</code> 屬性來設定事件處理函式，更多現代覽瀏器（包括 Firefox）也支援使用標準的 <code><a href="/zh-TW/docs/Web/API/EventTarget/addEventListener">addEventListener()</a></code> API 註冊監聽 <code>XMLHttpRequest</code> 的事件。</p> + +<dl> +</dl> + +<h2 id="方法">方法</h2> + +<dl> + <dt>{{domxref("XMLHttpRequest.abort()")}}</dt> + <dd>中止已發出的請求。</dd> + <dt>{{domxref("XMLHttpRequest.getAllResponseHeaders()")}}</dt> + <dd>回傳所有的回應標頭（response headers），為一以斷行字元（<a href="/zh-TW/docs/Glossary/CRLF">CRLF</a>）分行的字串，如未接收到回應則為 <code>null</code>。</dd> + <dt>{{domxref("XMLHttpRequest.getResponseHeader()")}}</dt> + <dd>回傳指定標頭文字之字串，假如回應尚未被接收或是標頭不存在於回應中則為 <code>null</code>。</dd> + <dt>{{domxref("XMLHttpRequest.open()")}}</dt> + <dd>初始化一個請求。此方法用於 JavaScript 中；若要在 native code 中初始化請求，請以 <a class="internal" href="/zh-TW/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIXMLHttpRequest#openRequest()"><code>openRequest()</code></a> 作為替代。</dd> + <dt>{{domxref("XMLHttpRequest.overrideMimeType()")}}</dt> + <dd>覆寫伺服器回傳的 MIME type。</dd> + <dt>{{domxref("XMLHttpRequest.send()")}}<span style="display: none;"> </span></dt> + <dd>發送請求。如果為非同步請求（預設值），此方法將在發出請求後便立即回傳（return）。</dd> + <dt>{{domxref("XMLHttpRequest.setRequestHeader()")}}</dt> + <dd>設定 HTTP 請求標頭（request header）值。<code>setRequestHeader()</code> 可被呼叫的時間點必須於 <a href="#open"><code>open()</code></a> 之後、在 <code>send()</code> 之前。</dd> +</dl> + +<h3 id="非標準方法">非標準方法</h3> + +<dl> + <dt>{{domxref("XMLHttpRequest.init()")}}</dt> + <dd>使用 C++ 程式時，用來初始化這個物件。</dd> +</dl> + +<div class="warning"><strong>注意:</strong> 請勿在 JavaScript 中呼叫這個方法。</div> + +<dl> + <dt>{{domxref("XMLHttpRequest.openRequest()")}}</dt> + <dd>初始化請求。這方法是用於原生程式，若想在 JavaScript 中初始化一個請求，請使用 <a class="internal" href="/zh-TW/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIXMLHttpRequest#open()"><code>open()</code></a> 這個方法來代替。請參照 <code>open()</code> 的相關文件。</dd> + <dt>{{domxref("XMLHttpRequest.sendAsBinary()")}}{{deprecated_inline()}}</dt> + <dd>另一種 <code>send()</code> 方法，用來送出二進位資料。</dd> +</dl> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">註解</th> + </tr> + <tr> + <td>{{SpecName('XMLHttpRequest')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td>Live standard, latest version</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + + + +<div>{{Compat("api.XMLHttpRequest")}}</div> + +<h2 id="參見">參見</h2> + +<ul> + <li>MDN 上涵蓋 XMLHttpRequest 的相關教學： + <ul> + <li><a href="/zh-TW/docs/AJAX/Getting_Started">Ajax — Getting Started</a></li> + <li><a href="/zh-TW/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest">使用 XMLHttpRequest</a></li> + <li><a href="/zh-TW/docs/Web/API/XMLHttpRequest/HTML_in_XMLHttpRequest">HTML in XMLHttpRequest</a></li> + <li><a href="/zh-TW/docs/Web/API/FormData"><code>FormData</code></a></li> + </ul> + </li> + <li><a class="external" href="http://www.html5rocks.com/en/tutorials/file/xhr2/">HTML5 Rocks — New Tricks in XMLHttpRequest2</a></li> + <li><code>Chrome scope availability</code> — how to access XMLHttpRequest from JSM modules etc., which do not have access to DOM + <ul> + <li><a href="/zh-TW/docs/Mozilla/Tech/XPCOM/Language_Bindings/Components.utils.importGlobalProperties">Components.utils.importGlobalProperties</a></li> + <li><a href="/zh-TW/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIXMLHttpRequest">nsIXMLHttpRequest</a></li> + </ul> + </li> +</ul> diff --git a/files/zh-tw/web/api/xmlhttprequest/onreadystatechange/index.html b/files/zh-tw/web/api/xmlhttprequest/onreadystatechange/index.html new file mode 100644 index 0000000000..817daf0efa --- /dev/null +++ b/files/zh-tw/web/api/xmlhttprequest/onreadystatechange/index.html @@ -0,0 +1,113 @@ +--- +title: XMLHttpRequest.onreadystatechange +slug: Web/API/XMLHttpRequest/onreadystatechange +translation_of: Web/API/XMLHttpRequest/onreadystatechange +--- +<div>{{APIRef}}</div> + +<p>An <a href="/docs/Web/API/EventHandler" title="A possible way to get notified of Events of a particular type (such as click) for a given object is to specify an event handler using:"><code>EventHandler</code></a> that is called whenever the <code>readyState</code> attribute changes. The callback is called from the user interface thread. The <strong><code>XMLHttpRequest.onreadystatechange</code></strong> property contains the event handler to be called when the {{event("readystatechange")}} event is fired, that is every time the {{domxref("XMLHttpRequest.readyState", "readyState")}} property of the {{domxref("XMLHttpRequest")}} changes.</p> + +<div class="warning"> +<p><strong>Warning:</strong> This should not be used with synchronous requests and must not be used from native code.</p> +</div> + +<p>The <code>readystatechange</code> event will not be fired when an <code>XMLHttpRequest</code> request is cancelled with the <a href="/docs/Web/API/XMLHttpRequest/abort">abort()</a> method.</p> + +<div class="note"> +<p>UPDATE: it's firing in the latest version of browsers (Firefox 51.0.1, Opera 43.0.2442.991, Safari 10.0.3 (12602.4.8), Chrome 54.0.2840.71, Edge, IE11). Example <a href="https://jsfiddle.net/merksam/ve5oc0gn/">here</a> - just reaload page few times.</p> +</div> + +<h2 id="Syntax" name="Syntax">語法</h2> + +<pre class="syntaxbox"><em>XMLHttpRequest</em>.onreadystatechange = <em>callback</em>;</pre> + +<h3 id="值">值</h3> + +<ul> + <li><code><em>callback</em></code> is the function to be executed when the <code>readyState</code> changes.</li> +</ul> + +<h2 id="Example" name="Example">範例</h2> + +<pre class="brush: js">var xhr = new XMLHttpRequest(), + method = "GET", + url = "https://developer.mozilla.org/"; + +xhr.open(<em>method</em>, <em>url</em>, true); +xhr.onreadystatechange = function () { + if(xhr.readyState === XMLHttpRequest.DONE && xhr.status === 200) { + console.log(xhr.responseText); + } + }; +xhr.send();</pre> + +<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', '#handler-xhr-onreadystatechange')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td>WHATWG living standard</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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(1)}}</td> + <td>{{CompatGeckoDesktop(1.0)}}</td> + <td>{{CompatIe(7)}}<sup>[1]</sup></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatSafari(1.2)}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>1.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Internet Explorer version 5 and 6 supported ajax calls using <code>ActiveXObject()</code>.</p> diff --git a/files/zh-tw/web/api/xmlhttprequest/readystate/index.html b/files/zh-tw/web/api/xmlhttprequest/readystate/index.html new file mode 100644 index 0000000000..3f7e909fe0 --- /dev/null +++ b/files/zh-tw/web/api/xmlhttprequest/readystate/index.html @@ -0,0 +1,148 @@ +--- +title: XMLHttpRequest.readyState +slug: Web/API/XMLHttpRequest/readyState +translation_of: Web/API/XMLHttpRequest/readyState +--- +<p>{{APIRef('XMLHttpRequest')}}</p> + +<p><strong>XMLHttpRequest.readyState</strong> 屬性會回傳一個 XMLHttpRequest 客戶端物件目前的狀態。一個 <abbr title="XMLHttpRequest">XHR</abbr> 客戶端可以為下列其中一種狀態：</p> + +<table class="standard-table"> + <tbody> + <tr> + <td class="header">值</td> + <td class="header">狀態</td> + <td class="header">說明</td> + </tr> + <tr> + <td><code>0</code></td> + <td><code>UNSENT</code></td> + <td>客戶端已被建立，但 <code>open()</code> 方法尚未被呼叫。</td> + </tr> + <tr> + <td><code>1</code></td> + <td><code>OPENED</code></td> + <td><code>open()</code> 方法已被呼叫。</td> + </tr> + <tr> + <td><code>2</code></td> + <td><code>HEADERS_RECEIVED</code></td> + <td><code>send()</code> 方法已被呼叫，而且可取得 header 與狀態。</td> + </tr> + <tr> + <td><code>3</code></td> + <td><code>LOADING</code></td> + <td>回應資料下載中，此時 <code>responseText</code> 會擁有部分資料。</td> + </tr> + <tr> + <td><code>4</code></td> + <td><code>DONE</code></td> + <td>完成下載操作。</td> + </tr> + </tbody> +</table> + +<dl> + <dt>UNSENT</dt> + <dd>XMLHttpRequest 客戶端物件已被建立，但 open() 方法尚未被呼叫。</dd> + <dt>OPENED</dt> + <dd>open() 方法已被呼叫。於此狀態時，可以使用 <a href="/zh-TW/docs/Web/API/XMLHttpRequest/setRequestHeader">setRequestHeader()</a> 方法設定請求標頭（request headers），並可呼叫 <a href="/zh-TW/docs/Web/API/XMLHttpRequest/send">send()</a> 方法來發送請求。</dd> + <dt>HEADERS_RECEIVED</dt> + <dd>send() 方法已被呼叫，並且已接收到回應標頭（response header）。</dd> + <dt>LOADING</dt> + <dd>正在接收回應內容（response's body）。如 <code><a href="/zh-TW/docs/Web/API/XMLHttpRequest/responseType">responseType</a></code> 屬性為 "text" 或空字串，則 <code><a href="/zh-TW/docs/Web/API/XMLHttpRequest/responseText">responseText</a></code> 屬性將會在載入的過程中擁有已載入部分之回應（response）內容中的文字。</dd> + <dt>DONE</dt> + <dd>請求操作已完成。這意味著資料傳輸可能已成功完成或是已失敗。</dd> +</dl> + +<div class="note"> +<p>這些狀態名稱在 Internet Explorer 中略有不同。其中 <code>UNSENT</code>, <code>OPENED</code>,<code> HEADERS_RECEIVED</code>,<code> LOADING</code> 和 <code>DONE 變成了 READYSTATE_UNINITIALIZED</code> (0), <code>READYSTATE_LOADING</code> (1), <code>READYSTATE_LOADED</code> (2), <code>READYSTATE_INTERACTIVE</code> (3) 和<code>READYSTATE_COMPLETE</code> (4)。</p> +</div> + +<h2 id="範例">範例</h2> + +<pre class="brush: js">var xhr = new XMLHttpRequest(); +console.log('UNSENT', xhr.readyState); // readyState will be 0 + +xhr.open('GET', '/api', true); +console.log('OPENED', xhr.readyState); // readyState will be 1 + +xhr.onprogress = function () { + console.log('LOADING', xhr.readyState); // readyState will be 3 +}; + +xhr.onload = function () { + console.log('DONE', xhr.readyState); // readyState will be 4 +}; + +xhr.send(null); +</pre> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">註解</th> + </tr> + <tr> + <td>{{SpecName('XMLHttpRequest', '#states')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td>WHATWG living standard</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<div>{{CompatibilityTable}}</div> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>功能</th> + <th>Chrome</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari (WebKit)</th> + </tr> + <tr> + <td>基本支援</td> + <td>{{CompatChrome(1)}}</td> + <td>{{CompatGeckoDesktop("1.0")}}<sup>[1]</sup></td> + <td>{{CompatIe(7)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatSafari("1.2")}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>功能</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>基本支援</td> + <td>{{CompatUnknown}}</td> + <td>1.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> diff --git a/files/zh-tw/web/api/xmlhttprequest/setrequestheader/index.html b/files/zh-tw/web/api/xmlhttprequest/setrequestheader/index.html new file mode 100644 index 0000000000..a8219e7240 --- /dev/null +++ b/files/zh-tw/web/api/xmlhttprequest/setrequestheader/index.html @@ -0,0 +1,66 @@ +--- +title: XMLHttpRequest.setRequestHeader() +slug: Web/API/XMLHttpRequest/setRequestHeader +translation_of: Web/API/XMLHttpRequest/setRequestHeader +--- +<div>{{APIRef('XMLHttpRequest')}}</div> + +<p>{{domxref("XMLHttpRequest")}} 物件中的 <code><strong>setRequestHeader()</strong></code> 方法用來設定 HTTP 的表頭請求。當使用 <code>setRequestHeader()</code> 的時候，必須在 {{domxref("XMLHttpRequest.open", "open()")}} 之後呼叫，同時也必須在 {{domxref("XMLHttpRequest.send", "send()")}} 之前呼叫。如果這個方法被呼叫了許多次，且設定的表頭是一樣的，那所有設定的值會被合併成一個單一的表頭請求。</p> + +<p>在第一次呼叫 <code>setRequestHeader()</code> 之後的每一次的呼叫，都會把給定的文字附加在已存在的表頭內容之後。</p> + +<p>If no {{HTTPHeader("Accept")}} header has been set using this, an <code>Accept</code> header with the type <code>"*/*"</code> is sent with the request when {{domxref("XMLHttpRequest.send", "send()")}} is called.</p> + +<p>基於安全的理由，有些表頭只有使用者代理器可以使用。這些表頭包含了： {{Glossary("Forbidden_header_name", "forbidden header names", 1)}} 和 {{Glossary("Forbidden_response_header_name", "forbidden response header names", 1)}}.</p> + +<div class="note"> +<p><strong>Note:</strong> For your custom fields, you may encounter a "<strong>not allowed by Access-Control-Allow-Headers in preflight response</strong>" exception when you send requests across domains. In this situation, you need to set up the {{HTTPHeader("Access-Control-Allow-Headers")}} in your response header at server side.</p> +</div> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><em>XMLHttpRequest</em>.setRequestHeader(<var>header</var>, <var>value</var>) +</pre> + +<h3 id="參數">參數</h3> + +<dl> + <dt><code>header</code></dt> + <dd>想要設定所屬值的表頭名稱。</dd> + <dt><code>value</code></dt> + <dd>用來設定表頭本身的值。</dd> +</dl> + +<h3 id="回傳值">回傳值</h3> + +<p><font face="consolas, Liberation Mono, courier, monospace"><span style="background-color: rgba(220, 220, 220, 0.5);">未定義</span></font>。</p> + +<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', '#the-setrequestheader()-method', 'setRequestHeader()')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td>WHATWG living standard</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + + + +<p>{{Compat("api.XMLHttpRequest.setRequestHeader")}}</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest">Using XMLHttpRequest</a></li> + <li><a href="/en-US/docs/Web/API/XMLHttpRequest/HTML_in_XMLHttpRequest">HTML in XMLHttpRequest</a></li> +</ul> diff --git a/files/zh-tw/web/api/xmlhttprequest/status/index.html b/files/zh-tw/web/api/xmlhttprequest/status/index.html new file mode 100644 index 0000000000..c54ece9939 --- /dev/null +++ b/files/zh-tw/web/api/xmlhttprequest/status/index.html @@ -0,0 +1,115 @@ +--- +title: XMLHttpRequest.status +slug: Web/API/XMLHttpRequest/status +translation_of: Web/API/XMLHttpRequest/status +--- +<div>{{APIRef('XMLHttpRequest')}}</div> + +<p><strong>XMLHttpRequest.status</strong> 屬性根據XMLHttpRequest的回應傳回數值化的狀況編碼。狀況編碼為一正短整數（<code>unsigned short）。</code>Before the request is complete, the value of <code>status</code> will be <code>0</code>. It is worth noting that browsers report a status of 0 in case of XMLHttpRequest errors too.</p> + +<p>The status codes returned are the standard <a href="/en-US/docs/Web/HTTP/Response_codes">HTTP status codes</a>. For example, <code>status</code> <code>200</code> denotes a successful request. If the server response doesn't explicitly specify a status code, <code>XMLHttpRequest.status</code> will assume the default value of <code>200</code>.</p> + +<h2 id="Example">Example</h2> + +<pre class="brush: js">var xhr = new XMLHttpRequest(); +console.log('UNSENT', xhr.status); + +xhr.open('GET', '/server', true); +console.log('OPENED', xhr.status); + +xhr.onprogress = function () { + console.log('LOADING', xhr.status); +}; + +xhr.onload = function () { + console.log('DONE', xhr.status); +}; + +xhr.send(null); + +/** + * Outputs the following: + * + * UNSENT 0 + * OPENED 0 + * LOADING 200 + * DONE 200 + */ +</pre> + +<h2 id="Specifications">Specifications</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', '#the-status-attribute')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td>WHATWG living standard</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatChrome(1)}}</td> + <td>{{CompatGeckoDesktop("1.0")}}<sup>[1]</sup></td> + <td>{{CompatIe(7)}}<sup>[1]</sup></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatSafari("1.2")}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>1.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Internet Explorer versions 5 and 6 lacked the XMLHttpRequest object, but provided a way to make AJAX requests using <code>ActiveXObject</code>.</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li>List of <a href="/en-US/docs/Web/HTTP/Response_codes">HTTP response codes</a></li> +</ul> diff --git a/files/zh-tw/web/api/xmlhttprequest/synchronous_and_asynchronous_requests/index.html b/files/zh-tw/web/api/xmlhttprequest/synchronous_and_asynchronous_requests/index.html new file mode 100644 index 0000000000..e8a148b5a9 --- /dev/null +++ b/files/zh-tw/web/api/xmlhttprequest/synchronous_and_asynchronous_requests/index.html @@ -0,0 +1,260 @@ +--- +title: Synchronous and asynchronous requests +slug: Web/API/XMLHttpRequest/Synchronous_and_Asynchronous_Requests +translation_of: Web/API/XMLHttpRequest/Synchronous_and_Asynchronous_Requests +--- +<p><code>XMLHttpRequest 支持同步和非同步請求，一般來說，建議使用非同步請求。</code></p> + +<p>In short, synchronous requests block the execution of code which creates "freezing" on the screen and an unresponsive user experience. </p> + +<h2 id="非同步請求">非同步請求</h2> + +<p>If you use <code>XMLHttpRequest</code> from an extension, you should use it asynchronously. In this case, you receive a callback when the data has been received, which lets the browser continue to work as normal while your request is being handled.</p> + +<h3 id="範例_send_a_file_to_the_console_log">範例: send a file to the console log</h3> + +<p>這是使用非同步<span style="font-family: consolas,monaco,andale mono,monospace;">XMLHttpRequest的基本方式</span></p> + +<pre class="brush: js">var xhr = new XMLHttpRequest(); +xhr.open("GET", "/bar/foo.txt", true); +xhr.onload = function (e) { + if (xhr.readyState === 4) { + if (xhr.status === 200) { + console.log(xhr.responseText); + } else { + console.error(xhr.statusText); + } + } +}; +xhr.onerror = function (e) { + console.error(xhr.statusText); +}; +xhr.send(null); </pre> + +<p>Line 2第3個參數為布林值，true表示非同步請求。</p> + +<p>Line 3 creates an event handler function object and assigns it to the request's <code>onload</code> attribute. This handler looks at the request's <code>readyState</code> to see if the transaction is complete in line 4, and if it is, and the HTTP status is 200, dumps the received content. If an error occurred, an error message is displayed.</p> + +<p>Line 15 actually initiates the request. The callback routine is called whenever the state of the request changes.</p> + +<h3 id="Example_creating_a_standard_function_to_read_external_files">Example: creating a standard function to read external files</h3> + +<p>In some cases you must read many external files. This is a standard function which uses the <code>XMLHttpRequest</code> object asynchronously in order to switch the content of the read file to a specified listener.</p> + +<pre class="brush: js">function xhrSuccess () { this.callback.apply(this, this.arguments); } + +function xhrError () { console.error(this.statusText); } + +function loadFile (sURL, fCallback /*, argumentToPass1, argumentToPass2, etc. */) { + var oReq = new XMLHttpRequest(); + oReq.callback = fCallback; + oReq.arguments = Array.prototype.slice.call(arguments, 2); + oReq.onload = xhrSuccess; + oReq.onerror = xhrError; + oReq.open("get", sURL, true); + oReq.send(null); +} +</pre> + +<p>Usage:</p> + +<pre class="brush: js">function showMessage (sMsg) { + alert(sMsg + this.responseText); +} + +loadFile("message.txt", showMessage, "New message!\n\n"); +</pre> + +<p>Line 1 declares a function which will pass all arguments after the third to the <font face="Courier New, Andale Mono, monospace"><span style="line-height: normal;">callback </span></font>function when the file has been loaded.</p> + +<p>Line 4 creates an event handler function object and assigns it to the request's <code>onload</code> attribute. This handler looks at the request's <code>readyState</code> to see if the transaction is complete in line 5, and if it is, and the HTTP status is 200, calls the callback function. If an error occurred, an error message is displayed.</p> + +<p>Line 13 specifies <code>true</code> for its third parameter to indicate that the request should be handled asynchronously.</p> + +<p>Line 14 actually initiates the request.</p> + +<h3 id="Example_using_a_timeout">Example: using a timeout</h3> + +<p>You can use a timeout to prevent hanging your code forever while waiting for a read to occur. This is done by setting the value of the <code>timeout</code> property on the <code>XMLHttpRequest</code> object, as shown in the code below:</p> + +<pre class="brush: js"> var args = arguments.slice(2); + var xhr = new XMLHttpRequest(); + xhr.ontimeout = function () { + console.error("The request for " + url + " timed out."); + }; + xhr.onload = function() { + if (xhr.readyState === 4) { + if (xhr.status === 200) { + callback.apply(xhr, args); + } else { + console.error(xhr.statusText); + } + } + }; + xhr.open("GET", url, true); + xhr.timeout = timeout; + xhr.send(null); +} +</pre> + +<p>Notice the addition of code to handle the "timeout" event by setting the <code>ontimeout</code> handler.</p> + +<p>Usage:</p> + +<pre class="brush: js">function showMessage (sMsg) { + alert(sMsg + this.responseText); +} + +loadFile("message.txt", 2000, showMessage, "New message!\n"); +</pre> + +<p>Here, we're specifying a timeout of 2000 ms.</p> + +<div class="note"> +<p><strong>Note:</strong> Support for <code>timeout</code> was added in {{Gecko("12.0")}}.</p> +</div> + +<h2 id="Synchronous_request">Synchronous request</h2> + +<div class="note"><strong>Note:</strong> Starting with Gecko 30.0 {{ geckoRelease("30.0") }}, synchronous requests on the main thread have been deprecated due to the negative effects to the user experience.</div> + +<p>In rare cases, the use of a synchronous method is preferable to an asynchronous one.</p> + +<h3 id="Example_HTTP_synchronous_request">Example: HTTP synchronous request</h3> + +<p>This example demonstrates how to make a simple synchronous request.</p> + +<pre class="brush: js">var request = new XMLHttpRequest(); +request.open('GET', '/bar/foo.txt', false); // `false` makes the request synchronous +request.send(null); + +if (request.status === 200) { + console.log(request.responseText); +} +</pre> + +<p>Line 3 sends the request. The <code>null</code> parameter indicates that no body content is needed for the <code>GET</code> request.</p> + +<p>Line 5 checks the status code after the transaction is completed. If the result is 200 -- HTTP's "OK" result -- the document's text content is output to the console.</p> + +<h3 id="Example_Synchronous_HTTP_request_from_a_Worker">Example: Synchronous HTTP request from a <code>Worker</code></h3> + +<p>One of the few cases in which a synchronous request does not usually block execution is the use of <code>XMLHttpRequest</code> within a <code><a href="/en/DOM/Worker" title="/en/DOM/Worker">Worker</a></code>.</p> + +<p><code><strong>example.html</strong></code> (the main page):</p> + +<pre class="brush: html"><!doctype html> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> +<title>MDN Example</title> +<script type="text/javascript"> + var worker = new Worker("myTask.js"); + worker.onmessage = function(event) { + alert("Worker said: " + event.data); + }; + + worker.postMessage("Hello"); +</script> +</head> +<body></body> +</html> +</pre> + +<p><code><strong>myFile.txt</strong></code> (the target of the synchronous <code><a href="/en/DOM/XMLHttpRequest" title="/en/XMLHttpRequest">XMLHttpRequest</a></code> invocation):</p> + +<pre>Hello World!! +</pre> + +<p><code><strong>myTask.js</strong></code> (the <code><a href="/en/DOM/Worker" title="/en/DOM/Worker">Worker</a></code>):</p> + +<pre class="brush: js">self.onmessage = function (event) { + if (event.data === "Hello") { + var xhr = new XMLHttpRequest(); + xhr.open("GET", "myFile.txt", false); // synchronous request + xhr.send(null); + self.postMessage(xhr.responseText); + } +}; +</pre> + +<div class="note"><strong>Note:</strong> The effect, because of the use of the <code>Worker</code>, is however asynchronous.</div> + +<p>It could be useful in order to interact in background with the server or to preload some content. See <a class="internal" href="/En/DOM/Using_web_workers" title="en/Using DOM workers">Using web workers</a> for examples and details.</p> + +<h3 id="Irreplaceability_of_the_synchronous_use">Irreplaceability of the synchronous use</h3> + +<p>There are some few cases in which the synchronous usage of XMLHttpRequest is not replaceable. This happens for example during the <a class="internal" href="/en/DOM/window.onunload" title="en/DOM/window.onunload"><code>window.onunload</code></a> and <a class="internal" href="/en/DOM/window.onbeforeunload" title="en/DOM/window.onbeforeunload"><code>window.onbeforeunload</code></a> events (<a class="internal" href="#XMLHttpRequests_being_stopped" title="en/XMLHttpRequest/Using_XMLHttpRequest#XMLHttpRequests_being_stopped">see also below</a>).</p> + +<p>Sending the usual XMLHttpRequest when the page unloaded poses a problem with the asynchronous response from the server: by the time the response comes back, the page has unloaded and the callback function won’t exist anymore. This generates a JavaScript “function is not defined” error.</p> + +<p style="text-align: center;"><img alt="" class="internal" src="/@api/deki/files/6227/=AsyncUnload.jpg" style="height: 359px; width: 467px;"></p> + +<p>A possible solution is to make sure that any AJAX requests that you make on unload are make synchronously instead of asynchronously. This will ensure that the page doesn’t finish unloading before the server response comes back.</p> + +<h4 id="Example_1_Automatic_logout_before_exit">Example #1: Automatic logout before exit</h4> + +<pre class="brush: js">window.onbeforeunload = function () { + var xhr = new XMLHttpRequest(); + xhr.open("GET", "logout.php?nick=" + escape(myName), false); // synchronous request + xhr.send(null); + if (xhr.responseText.trim() !== "logout done"); { // "logout done" is the expected response text + return "Logout has failed. Do you want to complete it manually?"; + } +}; +</pre> + +<h4 id="Example_2_Noting_if_a_user_abandon_the_site_without_clicking_any_link_and_registering_the_boring_page">Example #2: Noting if a user abandon the site without clicking any link and registering the boring page</h4> + +<pre class="brush: js"><!doctype html> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> +<title>MDN Example</title> +<script type="text/javascript"> +(function () { + + function dontPanic () { + bForsake = false; + return true; + } + + onload = function () { + for ( + var aLinks = document.links, nLen = aLinks.length, nIdx = 0; + nIdx < nLen; + aLinks[nIdx++].onclick = dontPanic + ); + }; + + onbeforeunload = function () { + if (bForsake) { + /* silent synchronous request */ + var oReq = new XMLHttpRequest(); + oReq.open("GET", "exit.php?leave=" + escape(location.href), false); + oReq.send(null); + } + }; + + var bForsake = true; + +})(); +</script> +</head> + +<body> + +<p><a href="https://developer.mozilla.org/">Example link</a></p> + +</body> +</html></pre> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/XMLHttpRequest" title="https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest"><code>XMLHttpRequest</code></a></li> + <li><a href="/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest" title="https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest">Using XMLHttpRequest</a></li> + <li><a href="/en-US/docs/AJAX" title="/en-US/docs/AJAX">AJAX</a></li> +</ul> + +<p>{{ languages( {"zh-cn": "zh-cn/DOM/XMLHttpRequest/Synchronous_and_Asynchronous_Requests" } ) }}</p> diff --git a/files/zh-tw/web/api/xmlhttprequest/using_xmlhttprequest/index.html b/files/zh-tw/web/api/xmlhttprequest/using_xmlhttprequest/index.html new file mode 100644 index 0000000000..97b03c21d1 --- /dev/null +++ b/files/zh-tw/web/api/xmlhttprequest/using_xmlhttprequest/index.html @@ -0,0 +1,766 @@ +--- +title: 使用 XMLHttpRequest +slug: Web/API/XMLHttpRequest/Using_XMLHttpRequest +tags: + - AJAX + - AJAXfile + - Advanced + - DOM + - JXON + - MakeBrowserAgnostic + - NeedsCompatTable + - XML + - XMLHttpRequest +translation_of: Web/API/XMLHttpRequest/Using_XMLHttpRequest +--- +<p>要送出一個 HTTP 請求，需要建立一個 {{domxref("XMLHttpRequest")}} 物件、開啟一個 URL，並發起一個請求。在交易（transaction）完成後，<code>XMLHttpRequest</code> 物件將會包含如回應內容（response body）及 <a href="/docs/Web/HTTP/Status">HTTP 狀態</a>等等請求結果中的有用資訊。本頁概述了一些常見的、甚至略為難理解的 <code>XMLHttpRequest</code> 物件使用案例。</p> + +<pre class="brush: js">function reqListener () { + console.log(this.responseText); +} + +var oReq = new XMLHttpRequest(); +oReq.addEventListener("load", reqListener); +oReq.open("GET", "http://www.example.org/example.txt"); +oReq.send();</pre> + +<h2 id="請求類型">請求類型</h2> + +<p>透過 <code>XMLHttpRequest</code> 建立的請求，其取得資料的方式可以為非同步（asynchronously）或同步（synchronously）兩種之一。請求的種類是由 {{domxref("XMLHttpRequest.open()")}} 方法的選擇性參數 <code>async</code>（第三個參數）決定。若 <code>async</code> 參數為 <code>true</code> 或是未指定，<code>XMLHttpRequest</code> 會被設定為非同步，相反的若為 <code>false</code> 則會被設定為同步。這兩種請求類型的細節討論與示範可以在<a href="/docs/DOM/XMLHttpRequest/Synchronous_and_Asynchronous_Requests">同步與非同步請求</a>頁面中找到。一般來說，很少會使用到同步請求。</p> + +<div class="note"><strong>備註：</strong>自 Gecko 30.0 {{ geckoRelease("30.0") }} 開始，在主執行緒上的同步請求因其差勁的使用者體驗已被棄用。</div> + +<h2 id="處理回應">處理回應</h2> + +<p><code>XMLHttpRequest</code> 的活動標準規範（living standard specification）定義了數個 <code>XMLHttpRequest</code> 建構出之物件的<a href="https://xhr.spec.whatwg.org/">回應屬性</a>。這些回應屬性告訴客戶端關於 <code>XMLHttpRequest</code> 回應狀態的重要資訊。一些處理非文字類型回應的案例可能會需要一些在下面小節所說明的分析和操作。</p> + +<h3 id="分析及操作_responseXML_屬性">分析及操作 <code>responseXML</code> 屬性</h3> + +<p>透過 <code>XMLHttpRequest</code> 取得一個遠端的 XML 文件內容時，<code>responseXML</code> 屬性（{{Glossary("property/JavaScript", "property")}}）將會是一個由 XML 文件解析而來的 DOM 物件。這可能會造成分析和操作上的一些困難，以下有四種主要的 XML 文件分析方式：</p> + +<ol> + <li>利用 <a href="/docs/Web/XPath">XPath</a> 指向需要部份。</li> + <li>手動的<a href="/docs/Web/Guide/Parsing_and_serializing_XML">解析與序列化 XML</a> 成字串或物件。</li> + <li>利用 {{domxref("XMLSerializer")}} 來序列化 <strong>DOM 樹成字串或檔案</strong>。</li> + <li>如果事先知道 XML 文件內容，可利用 {{jsxref("RegExp")}}。如果換行符號會影響 <code>RegExp</code> 掃描結果，則需要移除換行符號。然而，這項方式應該是「最後不得已的手段（last resort）」，因為一旦 XML 文件內容稍有變動，此方式就可能會失敗。</li> +</ol> + +<h3 id="分析及操作含有_HTML_文件的_responseText_屬性">分析及操作含有 HTML 文件的 <code>responseText</code> 屬性</h3> + +<div class="note"><strong>備註：</strong>W3C 的<a href="https://dvcs.w3.org/hg/xhr/raw-file/tip/Overview.html">XMLHttpRequest</a> 規範允許透過 <code>XMLHttpRequest.responseXML</code> 屬性（{{Glossary("property/JavaScript", "property")}}）來解析 HTML。相關細節請參考 <a href="/docs/Web/API/XMLHttpRequest/HTML_in_XMLHttpRequest">HTML in XMLHttpRequest</a> 一文。</div> + +<p>若透過 <code>XMLHttpRequest</code> 來取得一個遠端的 HTML 網頁內容，則 <code>responseText</code> 屬性（{{Glossary("property/JavaScript", "property")}}）會是「一串（soup）」包含所有 HTML 標籤的字串。這可能使得在分析和操作上造成困難，以下有三種主要分析此一大串 HTML 字串的方式：</p> + +<ol> + <li>利用 <code>XMLHttpRequest.responseXML</code> 屬性。</li> + <li>將內容透過 <code>fragment.body.innerHTML</code> 注入<a href="/docs/Web/API/DocumentFragment">文件片段（document fragment）</a>之 <code>body</code> 中，並遍歷（traverse）文件片段的 DOM。</li> + <li>如果事先知道 HTML 之 <code>responseText</code> 內容，可利用 {{jsxref("RegExp")}}。如果換行符號會影響 <code>RegExp</code> 掃描結果，則需要移除換行符號。然而，這項方式應該是「最後不得已的手段（last resort）」，因為一旦 HTML 程式碼稍有變動，此方式就可能會失敗。</li> +</ol> + +<h2 id="處理二進位資料">處理二進位資料</h2> + +<p>僅管 <code>XMLHttpRequest</code> 最常被用在傳送及接收文字資料，但它其實也可以傳送及接收二進位內容。有幾種經過良好測試的方法可以用來強制使用 <code>XMLHttpRequest</code> 發送二進位資料。透過使用 <code>XMLHttpRequest</code> 物件的 <code>.overrideMimeType()</code> 方法是一個可行的解決方案。</p> + +<pre class="brush:js">var oReq = new XMLHttpRequest(); +oReq.open("GET", url); +// retrieve data unprocessed as a binary string +oReq.overrideMimeType("text/plain; charset=x-user-defined"); +/* ... */ +</pre> + +<p>XMLHttpRequest Level 2 規範加入了新的 <a href="https://xhr.spec.whatwg.org/#the-responsetype-attribute"><code>responseType</code> 屬性</a>，讓收發二進位資料變得容易許多。</p> + +<pre class="brush:js">var oReq = new XMLHttpRequest(); + +oReq.onload = function(e) { + var arraybuffer = oReq.response; // not responseText + /* ... */ +} +oReq.open("GET", url); +oReq.responseType = "arraybuffer"; +oReq.send();</pre> + +<p>更多的範例可參考<a href="/docs/DOM/XMLHttpRequest/Sending_and_Receiving_Binary_Data">傳送及接收二進位資料</a>頁面。</p> + +<h2 id="監視進度">監視進度</h2> + +<p><code>XMLHttpRequest</code> 提供了監聽請求於處理過程中所發生的各項事件之能力。包括了定期進度通知、錯誤通知等等。</p> + +<p><code>XMLHttpRequest</code> 支援可監視其傳輸進度的 DOM 進度事件，此事件遵循<a href="https://xhr.spec.whatwg.org/#interface-progressevent">進度事件規範</a>：這些事件實作了 {{domxref("ProgressEvent")}} 介面。</p> + +<pre class="brush:js">var oReq = new XMLHttpRequest(); + +oReq.addEventListener("progress", updateProgress); +oReq.addEventListener("load", transferComplete); +oReq.addEventListener("error", transferFailed); +oReq.addEventListener("abort", transferCanceled); + +oReq.open(); + +// ... + +// progress on transfers from the server to the client (downloads) +function updateProgress (oEvent) { + if (oEvent.lengthComputable) { + var percentComplete = oEvent.loaded / oEvent.total; + // ... + } else { + // Unable to compute progress information since the total size is unknown + } +} + +function transferComplete(evt) { + console.log("The transfer is complete."); +} + +function transferFailed(evt) { + console.log("An error occurred while transferring the file."); +} + +function transferCanceled(evt) { + console.log("The transfer has been canceled by the user."); +}</pre> + +<p>第 3-6 行加入了事件監聽器來處理使用 <code>XMLHttpRequest</code> 執行資料收發過程中的各類事件。</p> + +<div class="note"><strong>備註：</strong>必須在呼叫 <code>open()</code> 方法開啟請求連線之前就註冊好事件監聽器，否則 <code>progress</code> 事件將不會被觸發。</div> + +<p>在這個例子中，指定了 <code>updateProgress()</code> 函式作為 <code>progress</code> 事件處理器，<code>progress</code> 事件處理器會於 <code>progress</code> 事件物件的 <code>total</code> 及 <code>loaded</code> 屬性分別接收到要傳輸的總位元數及已送出的位元數。然而，假如 <code>lengthComputable</code> 屬性值為假，則代表要傳輸的總位元數是未知且 <code>total</code> 屬性值將會為零。</p> + +<p><code>progress</code> 事件同時存在於上傳及下載傳輸中。下載的相關事件會於 <code>XMLHttpRequest</code> 物件自己身上被觸發，如上面的範例。而上傳相關事件則在 <code>XMLHttpRequest.upload</code> 物件上被觸發，如以下範例：</p> + +<pre class="brush:js">var oReq = new XMLHttpRequest(); + +oReq.upload.addEventListener("progress", updateProgress); +oReq.upload.addEventListener("load", transferComplete); +oReq.upload.addEventListener("error", transferFailed); +oReq.upload.addEventListener("abort", transferCanceled); + +oReq.open(); +</pre> + +<div class="note"><strong>備註：</strong><code>progress</code> 事件無法用於 <code>file:</code> 通訊協定。</div> + +<div class="note"> +<p><strong>備註：</strong>自 {{Gecko("9.0")}} 開始，接收到每一個資料的區塊（chunk）時，<code>progress</code> 事件都會被觸發。包括在 <code>progress</code> 事件被觸發前，就已經接收到含有最後一個資料區塊的最後一個封包並且關閉連線的狀況下，在載入此封包時仍會自動觸發 <code>progress</code> 事件。這代表我們可以僅關注 <code>progress</code> 事件即能夠可靠的監視進度。</p> +</div> + +<div class="note"> +<p><strong>備註：</strong>在 {{Gecko("12.0")}} 中，如果 <code>XMLHttpRequest</code> 的 <code>responseType</code> 屬性為「moz-blob」，那麼 <code>progress</code> 事件觸發時的 <code>XMLHttpRequest.response</code> 值會是一個目前包含了所接收資料的 {{domxref("Blob")}}。</p> +</div> + +<p>我們也可以透過 <code>loadend</code> 事件來偵測到所有之三種下載結束狀況（<code>abort</code>、<code>load</code> 或 <code>error</code>）：</p> + +<pre class="brush:js">req.addEventListener("loadend", loadEnd); + +function loadEnd(e) { + console.log("The transfer finished (although we don't know if it succeeded or not)."); +} +</pre> + +<p>請注意由 <code>loadend</code> 事件中接收到的資訊並無法確定是由何種結束狀況所觸發。不過還是可以用 <code>loadend</code> 事件來處理所有傳輸結束情況下需要執行的任務。</p> + +<h2 id="提交表單與上傳檔案">提交表單與上傳檔案</h2> + +<p><code>XMLHttpRequest</code> 物件實體有兩種方式來提交表單：</p> + +<ul> + <li>僅使用 AJAX</li> + <li>使用 {{domxref("XMLHttpRequest.FormData", "FormData")}} API</li> +</ul> + +<p>使用 <code>FormData</code> API 是最簡單、快速的方式，但不利於將資料集合進行<a href="/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify">字串化</a>。<br> + 只使用 AJAX 的方式較為複雜，但也更加靈活、強大。</p> + +<h3 id="僅使用_XMLHttpRequest">僅使用 <code>XMLHttpRequest</code></h3> + +<p>以不透過 <code>FormData</code> API 提交表單的方式在大多數的情況下都不需要使用其他額外的 API。唯一的例外是<strong>要上傳一或多個檔案</strong>時，會需要用到 {{domxref("FileReader")}} API。</p> + +<h4 id="提交方法簡介">提交方法簡介</h4> + +<p>一個 HTML {{HTMLElement("form", "表單（form）")}}有以下四種提交方式：</p> + +<ul> + <li>使用 <code>POST</code> 方法，並且設定 <code>enctype</code> 屬性（{{Glossary("attribute")}}）為 <code>application/x-www-form-urlencoded</code>（預設值）。</li> + <li>使用 <code>POST</code> 方法，並且設定 <code>enctype</code> 屬性為 <code>text/plain</code>。</li> + <li>使用 <code>POST</code> 方法，並且設定 <code>enctype</code> 屬性為 <code>multipart/form-data</code>。</li> + <li>使用 <code>GET</code> 方法（在此情況下，<code>enctype</code> 屬性將會被忽略）。</li> +</ul> + +<p>現在，假設要提交一個只包含兩個欄位的表單，欄位名稱為 <code>foo</code> 及 <code>baz</code>。若是使用 <code>POST</code> 方法，伺服器將會收到一個如以下三個例子之一的字串，這取決於所使用的編碼類型（encoding type）：</p> + +<ul> + <li> + <p>方法：<code>POST</code>；編碼類型：<code>application/x-www-form-urlencoded</code>（預設值）：</p> + + <pre class="brush:plain">Content-Type: application/x-www-form-urlencoded + +foo=bar&baz=The+first+line.%0D%0AThe+second+line.%0D%0A</pre> + </li> + <li> + <p>方法：<code>POST</code>；編碼類型：<code>text/plain</code>：</p> + + <pre class="brush:plain">Content-Type: text/plain + +foo=bar +baz=The first line. +The second line.</pre> + </li> + <li> + <p>方法：<code>POST</code>；編碼類型：<code><a href="/docs/Web/HTTP/Basics_of_HTTP/MIME_types#multipartform-data">multipart/form-data</a></code>：</p> + + <pre class="brush:plain">Content-Type: multipart/form-data; boundary=---------------------------314911788813839 + +-----------------------------314911788813839 +Content-Disposition: form-data; name="foo" + +bar +-----------------------------314911788813839 +Content-Disposition: form-data; name="baz" + +The first line. +The second line. + +-----------------------------314911788813839--</pre> + </li> +</ul> + +<p>如果是使用 <code>GET</code> 方法，一個如下方的字串會被直接附加入到 URL 上：</p> + +<pre class="brush:plain">?foo=bar&baz=The%20first%20line.%0AThe%20second%20line.</pre> + +<h4 id="小型原生框架">小型原生框架</h4> + +<p>在我們提交 {{HTMLElement("form")}} 時，瀏覽器自動幫我們做了上面這些工作。假如要使用 JavaScript 達到同樣的效果就必須告訴直譯器（interpreter）要處理的<em>所有事</em>。然而，如何透過<em>純粹的</em> AJAX 來傳送表單複雜到難以在本頁解釋所有細節。基於這個理由，我們改為在這此提供<strong>一組完整（教學用）的框架</strong>，可用於上述四種的每一種<em>提交（submit）</em>，並包括<strong>上傳檔案</strong>：</p> + +<div style="height: 400px; margin-bottom: 12px; overflow: auto;"> +<pre class="brush: html"><!doctype html> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> +<title>Sending forms with pure AJAX &ndash; MDN</title> +<script type="text/javascript"> + +"use strict"; + +/*\ +|*| +|*| :: XMLHttpRequest.prototype.sendAsBinary() Polyfill :: +|*| +|*| https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest#sendAsBinary() +\*/ + +if (!XMLHttpRequest.prototype.sendAsBinary) { + XMLHttpRequest.prototype.sendAsBinary = function(sData) { + var nBytes = sData.length, ui8Data = new Uint8Array(nBytes); + for (var nIdx = 0; nIdx < nBytes; nIdx++) { + ui8Data[nIdx] = sData.charCodeAt(nIdx) & 0xff; + } + /* send as ArrayBufferView...: */ + this.send(ui8Data); + /* ...or as ArrayBuffer (legacy)...: this.send(ui8Data.buffer); */ + }; +} + +/*\ +|*| +|*| :: AJAX Form Submit Framework :: +|*| +|*| https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest +|*| +|*| This framework is released under the GNU Public License, version 3 or later. +|*| https://www.gnu.org/licenses/gpl-3.0-standalone.html +|*| +|*| Syntax: +|*| +|*| AJAXSubmit(HTMLFormElement); +\*/ + +var AJAXSubmit = (function () { + + function ajaxSuccess () { + /* console.log("AJAXSubmit - Success!"); */ + console.log(this.responseText); + /* you can get the serialized data through the "submittedData" custom property: */ + /* console.log(JSON.stringify(this.submittedData)); */ + } + + function submitData (oData) { + /* the AJAX request... */ + var oAjaxReq = new XMLHttpRequest(); + oAjaxReq.submittedData = oData; + oAjaxReq.onload = ajaxSuccess; + if (oData.technique === 0) { + /* method is GET */ + oAjaxReq.open("get", oData.receiver.replace(/(?:\?.*)?$/, + oData.segments.length > 0 ? "?" + oData.segments.join("&") : ""), true); + oAjaxReq.send(null); + } else { + /* method is POST */ + oAjaxReq.open("post", oData.receiver, true); + if (oData.technique === 3) { + /* enctype is multipart/form-data */ + var sBoundary = "---------------------------" + Date.now().toString(16); + oAjaxReq.setRequestHeader("Content-Type", "multipart\/form-data; boundary=" + sBoundary); + oAjaxReq.sendAsBinary("--" + sBoundary + "\r\n" + + oData.segments.join("--" + sBoundary + "\r\n") + "--" + sBoundary + "--\r\n"); + } else { + /* enctype is application/x-www-form-urlencoded or text/plain */ + oAjaxReq.setRequestHeader("Content-Type", oData.contentType); + oAjaxReq.send(oData.segments.join(oData.technique === 2 ? "\r\n" : "&")); + } + } + } + + function processStatus (oData) { + if (oData.status > 0) { return; } + /* the form is now totally serialized! do something before sending it to the server... */ + /* doSomething(oData); */ + /* console.log("AJAXSubmit - The form is now serialized. Submitting..."); */ + submitData (oData); + } + + function pushSegment (oFREvt) { + this.owner.segments[this.segmentIdx] += oFREvt.target.result + "\r\n"; + this.owner.status--; + processStatus(this.owner); + } + + function plainEscape (sText) { + /* How should I treat a text/plain form encoding? + What characters are not allowed? this is what I suppose...: */ + /* "4\3\7 - Einstein said E=mc2" ----> "4\\3\\7\ -\ Einstein\ said\ E\=mc2" */ + return sText.replace(/[\s\=\\]/g, "\\$&"); + } + + function SubmitRequest (oTarget) { + var nFile, sFieldType, oField, oSegmReq, oFile, bIsPost = oTarget.method.toLowerCase() === "post"; + /* console.log("AJAXSubmit - Serializing form..."); */ + this.contentType = bIsPost && oTarget.enctype ? oTarget.enctype : "application\/x-www-form-urlencoded"; + this.technique = bIsPost ? + this.contentType === "multipart\/form-data" ? 3 : this.contentType === "text\/plain" ? 2 : 1 : 0; + this.receiver = oTarget.action; + this.status = 0; + this.segments = []; + var fFilter = this.technique === 2 ? plainEscape : escape; + for (var nItem = 0; nItem < oTarget.elements.length; nItem++) { + oField = oTarget.elements[nItem]; + if (!oField.hasAttribute("name")) { continue; } + sFieldType = oField.nodeName.toUpperCase() === "INPUT" ? oField.getAttribute("type").toUpperCase() : "TEXT"; + if (sFieldType === "FILE" && oField.files.length > 0) { + if (this.technique === 3) { + /* enctype is multipart/form-data */ + for (nFile = 0; nFile < oField.files.length; nFile++) { + oFile = oField.files[nFile]; + oSegmReq = new FileReader(); + /* (custom properties:) */ + oSegmReq.segmentIdx = this.segments.length; + oSegmReq.owner = this; + /* (end of custom properties) */ + oSegmReq.onload = pushSegment; + this.segments.push("Content-Disposition: form-data; name=\"" + + oField.name + "\"; filename=\"" + oFile.name + + "\"\r\nContent-Type: " + oFile.type + "\r\n\r\n"); + this.status++; + oSegmReq.readAsBinaryString(oFile); + } + } else { + /* enctype is application/x-www-form-urlencoded or text/plain or + method is GET: files will not be sent! */ + for (nFile = 0; nFile < oField.files.length; + this.segments.push(fFilter(oField.name) + "=" + fFilter(oField.files[nFile++].name))); + } + } else if ((sFieldType !== "RADIO" && sFieldType !== "CHECKBOX") || oField.checked) { + /* NOTE: this will submit _all_ submit buttons. Detecting the correct one is non-trivial. */ + /* field type is not FILE or is FILE but is empty */ + this.segments.push( + this.technique === 3 ? /* enctype is multipart/form-data */ + "Content-Disposition: form-data; name=\"" + oField.name + "\"\r\n\r\n" + oField.value + "\r\n" + : /* enctype is application/x-www-form-urlencoded or text/plain or method is GET */ + fFilter(oField.name) + "=" + fFilter(oField.value) + ); + } + } + processStatus(this); + } + + return function (oFormElement) { + if (!oFormElement.action) { return; } + new SubmitRequest(oFormElement); + }; + +})(); + +</script> +</head> +<body> + +<h1>Sending forms with pure AJAX</h1> + +<h2>Using the GET method</h2> + +<form action="register.php" method="get" onsubmit="AJAXSubmit(this); return false;"> + <fieldset> + <legend>Registration example</legend> + <p> + First name: <input type="text" name="firstname" /><br /> + Last name: <input type="text" name="lastname" /> + </p> + <p> + <input type="submit" value="Submit" /> + </p> + </fieldset> +</form> + +<h2>Using the POST method</h2> +<h3>Enctype: application/x-www-form-urlencoded (default)</h3> + +<form action="register.php" method="post" onsubmit="AJAXSubmit(this); return false;"> + <fieldset> + <legend>Registration example</legend> + <p> + First name: <input type="text" name="firstname" /><br /> + Last name: <input type="text" name="lastname" /> + </p> + <p> + <input type="submit" value="Submit" /> + </p> + </fieldset> +</form> + +<h3>Enctype: text/plain</h3> + +<form action="register.php" method="post" enctype="text/plain" + onsubmit="AJAXSubmit(this); return false;"> + <fieldset> + <legend>Registration example</legend> + <p> + Your name: <input type="text" name="user" /> + </p> + <p> + Your message:<br /> + <textarea name="message" cols="40" rows="8"></textarea> + </p> + <p> + <input type="submit" value="Submit" /> + </p> + </fieldset> +</form> + +<h3>Enctype: multipart/form-data</h3> + +<form action="register.php" method="post" enctype="multipart/form-data" + onsubmit="AJAXSubmit(this); return false;"> + <fieldset> + <legend>Upload example</legend> + <p> + First name: <input type="text" name="firstname" /><br /> + Last name: <input type="text" name="lastname" /><br /> + Sex: + <input id="sex_male" type="radio" name="sex" value="male" /> + <label for="sex_male">Male</label> + <input id="sex_female" type="radio" name="sex" value="female" /> + <label for="sex_female">Female</label><br /> + Password: <input type="password" name="secret" /><br /> + What do you prefer: + <select name="image_type"> + <option>Books</option> + <option>Cinema</option> + <option>TV</option> + </select> + </p> + <p> + Post your photos: + <input type="file" multiple name="photos[]"> + </p> + <p> + <input id="vehicle_bike" type="checkbox" name="vehicle[]" value="Bike" /> + <label for="vehicle_bike">I have a bike</label><br /> + <input id="vehicle_car" type="checkbox" name="vehicle[]" value="Car" /> + <label for="vehicle_car">I have a car</label> + </p> + <p> + Describe yourself:<br /> + <textarea name="description" cols="50" rows="8"></textarea> + </p> + <p> + <input type="submit" value="Submit" /> + </p> + </fieldset> +</form> + +</body> +</html></pre> +</div> + +<p>為了進行測試，建立一個名為 <strong>register.php</strong> 的 PHP 頁面（即為上面範例表單之 <code>action</code> 屬性（{{Glossary("attribute")}}）所指向的位置），並輸入以下<em>最簡化</em>的內容：</p> + +<pre class="brush: php"><?php +/* register.php */ + +header("Content-type: text/plain"); + +/* +NOTE: You should never use `print_r()` in production scripts, or +otherwise output client-submitted data without sanitizing it first. +Failing to sanitize can lead to cross-site scripting vulnerabilities. +*/ + +echo ":: data received via GET ::\n\n"; +print_r($_GET); + +echo "\n\n:: Data received via POST ::\n\n"; +print_r($_POST); + +echo "\n\n:: Data received as \"raw\" (text/plain encoding) ::\n\n"; +if (isset($HTTP_RAW_POST_DATA)) { echo $HTTP_RAW_POST_DATA; } + +echo "\n\n:: Files received ::\n\n"; +print_r($_FILES); + +</pre> + +<p>使用這個框架的語法簡單如下：</p> + +<pre class="syntaxbox">AJAXSubmit(myForm);</pre> + +<div class="note"><strong>備註：</strong>此框架使用了 {{domxref("FileReader")}} API 來發送檔案上傳。這是個較新的 API，且 IE9 或其先前版本並未實作。因為這個理由，AJAX-only 上傳被認為是<strong>一項實驗性技術</strong>。若沒有需要上傳二進位檔案，此框架可於大部分瀏覽器中運作良好。</div> + +<div class="note"><strong>備註：</strong>傳送二進位檔案的最佳方式是藉由 {{jsxref("ArrayBuffer", "ArrayBuffers")}} 或 {{domxref("Blob", "Blobs")}} 結合 {{domxref("XMLHttpRequest.send()", "send()")}} 方法來送出，如果可以也能搭配 <code>FileReader</code> API 的 {{domxref("FileReader.readAsArrayBuffer()", "readAsArrayBuffer()")}} 方法先進行讀取。但因為這段程式指令碼（script）的目的是要處理<a href="/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify">可字串化的</a>原始資料，所以使用 {{domxref("XMLHttpRequest.sendAsBinary()", "sendAsBinary()")}} 方法結合 <code>FileReader</code> API 的 {{domxref("FileReader.readAsBinaryString()", "readAsBinaryString()")}} 方法。就其本身來看，以上的指令碼只有在處理小型檔案時才有意義。假如不打算上傳二進位內容，請考慮使用 <code>FormData</code> API。</div> + +<div class="note"><strong>備註：</strong>非標準的 <code>sendAsBinary</code> 方法在 Gecko 31 {{geckoRelease(31)}} 已被認為是棄用的（deprecated），並且即將被移除。而標準的 <code>send(Blob data)</code> 方法可以作為替代。</div> + +<h3 id="使用_FormData_物件">使用 FormData 物件</h3> + +<p>{{domxref("XMLHttpRequest.FormData", "FormData")}} 建構式可以讓我們收集一連串名／值對資料並透過 <code>XMLHttpRequest</code> 送出。其主要用於傳送表單資料，但也能夠單獨的由表單建立來傳輸使用者輸入的資料。若表單的編碼類型（encoding type）被設定為「multipart/form-data」，則由 <code>FormData</code> 所發送的資料格式和表單用來傳送資料的 <code>submit()</code> 方法相同。FormData 物件可以搭配 <code>XMLHttpRequest</code> 以多種方式使用。相關的範例，以及可以怎麼利用 FormData 配合 XMLHttpRequest 的說明，請參考<a href="/docs/DOM/XMLHttpRequest/FormData/Using_FormData_Objects">使用 FormData 物件</a>頁面。為了教學使用，下方為<strong>一個利用 <code>FormData</code> API 來改寫<a href="#小型原生框架">先前範例</a>的<em>翻譯</em>版本</strong>。注意這段精簡後的程式碼：</p> + +<div style="height: 400px; margin-bottom: 12px; overflow: auto;"> +<pre class="brush: html"><!doctype html> +<html> +<head> +<meta http-equiv="Content-Type" charset="UTF-8" /> +<title>Sending forms with FormData &ndash; MDN</title> +<script> +"use strict"; + +function ajaxSuccess () { + console.log(this.responseText); +} + +function AJAXSubmit (oFormElement) { + if (!oFormElement.action) { return; } + var oReq = new XMLHttpRequest(); + oReq.onload = ajaxSuccess; + if (oFormElement.method.toLowerCase() === "post") { + oReq.open("post", oFormElement.action); + oReq.send(new FormData(oFormElement)); + } else { + var oField, sFieldType, nFile, sSearch = ""; + for (var nItem = 0; nItem < oFormElement.elements.length; nItem++) { + oField = oFormElement.elements[nItem]; + if (!oField.hasAttribute("name")) { continue; } + sFieldType = oField.nodeName.toUpperCase() === "INPUT" ? + oField.getAttribute("type").toUpperCase() : "TEXT"; + if (sFieldType === "FILE") { + for (nFile = 0; nFile < oField.files.length; + sSearch += "&" + escape(oField.name) + "=" + escape(oField.files[nFile++].name)); + } else if ((sFieldType !== "RADIO" && sFieldType !== "CHECKBOX") || oField.checked) { + sSearch += "&" + escape(oField.name) + "=" + escape(oField.value); + } + } + oReq.open("get", oFormElement.action.replace(/(?:\?.*)?$/, sSearch.replace(/^&/, "?")), true); + oReq.send(null); + } +} +</script> +</head> +<body> + +<h1>Sending forms with FormData</h1> + +<h2>Using the GET method</h2> + +<form action="register.php" method="get" onsubmit="AJAXSubmit(this); return false;"> + <fieldset> + <legend>Registration example</legend> + <p> + First name: <input type="text" name="firstname" /><br /> + Last name: <input type="text" name="lastname" /> + </p> + <p> + <input type="submit" value="Submit" /> + </p> + </fieldset> +</form> + +<h2>Using the POST method</h2> +<h3>Enctype: application/x-www-form-urlencoded (default)</h3> + +<form action="register.php" method="post" onsubmit="AJAXSubmit(this); return false;"> + <fieldset> + <legend>Registration example</legend> + <p> + First name: <input type="text" name="firstname" /><br /> + Last name: <input type="text" name="lastname" /> + </p> + <p> + <input type="submit" value="Submit" /> + </p> + </fieldset> +</form> + +<h3>Enctype: text/plain</h3> + +<p>The text/plain encoding is not supported by the FormData API.</p> + +<h3>Enctype: multipart/form-data</h3> + +<form action="register.php" method="post" enctype="multipart/form-data" + onsubmit="AJAXSubmit(this); return false;"> + <fieldset> + <legend>Upload example</legend> + <p> + First name: <input type="text" name="firstname" /><br /> + Last name: <input type="text" name="lastname" /><br /> + Sex: + <input id="sex_male" type="radio" name="sex" value="male" /> + <label for="sex_male">Male</label> + <input id="sex_female" type="radio" name="sex" value="female" /> + <label for="sex_female">Female</label><br /> + Password: <input type="password" name="secret" /><br /> + What do you prefer: + <select name="image_type"> + <option>Books</option> + <option>Cinema</option> + <option>TV</option> + </select> + </p> + <p> + Post your photos: + <input type="file" multiple name="photos[]"> + </p> + <p> + <input id="vehicle_bike" type="checkbox" name="vehicle[]" value="Bike" /> + <label for="vehicle_bike">I have a bike</label><br /> + <input id="vehicle_car" type="checkbox" name="vehicle[]" value="Car" /> + <label for="vehicle_car">I have a car</label> + </p> + <p> + Describe yourself:<br /> + <textarea name="description" cols="50" rows="8"></textarea> + </p> + <p> + <input type="submit" value="Submit" /> + </p> + </fieldset> +</form> +</body> +</html></pre> +</div> + +<div class="note"><strong>備註：</strong>如同之前所說，<strong>{{domxref("FormData")}} 物件是不能被<a href="/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify">字串化</a>的物件</strong>。若想要字串化一個被提交的資料，請使用<a href="#小型原生框架">先前的<em>純</em> AJAX 範例</a>。還要注意的是，雖然在這個例子中有一些 <code>file</code> {{ HTMLElement("input") }} 欄位，<strong>當你透過 <code>FormData</code> API 來提交表單便也不需要使用 {{domxref("FileReader")}} API</strong>：檔案會自動地載入並上傳。</div> + +<h2 id="取得最後修改日期">取得最後修改日期</h2> + +<pre class="brush: js">function getHeaderTime () { + console.log(this.getResponseHeader("Last-Modified")); /* A valid GMTString date or null */ +} + +var oReq = new XMLHttpRequest(); +oReq.open("HEAD" /* use HEAD if you only need the headers! */, "yourpage.html"); +oReq.onload = getHeaderTime; +oReq.send();</pre> + +<h3 id="當最後修改日期改變時做一些事">當最後修改日期改變時做一些事</h3> + +<p>先建立兩個函式：</p> + +<pre class="brush: js">function getHeaderTime () { + var nLastVisit = parseFloat(window.localStorage.getItem('lm_' + this.filepath)); + var nLastModif = Date.parse(this.getResponseHeader("Last-Modified")); + + if (isNaN(nLastVisit) || nLastModif > nLastVisit) { + window.localStorage.setItem('lm_' + this.filepath, Date.now()); + isFinite(nLastVisit) && this.callback(nLastModif, nLastVisit); + } +} + +function ifHasChanged(sURL, fCallback) { + var oReq = new XMLHttpRequest(); + oReq.open("HEAD" /* use HEAD - we only need the headers! */, sURL); + oReq.callback = fCallback; + oReq.filepath = sURL; + oReq.onload = getHeaderTime; + oReq.send(); +}</pre> + +<p>並進行測試：</p> + +<pre class="brush: js">/* Let's test the file "yourpage.html"... */ + +ifHasChanged("yourpage.html", function (nModif, nVisit) { + console.log("The page '" + this.filepath + "' has been changed on " + (new Date(nModif)).toLocaleString() + "!"); +});</pre> + +<p>如果想要知道<strong><em>目前頁面</em><em>是否</em>已變更</strong>，請參考 {{domxref("document.lastModified")}} 一文。</p> + +<h2 id="跨網域_XMLHttpRequest">跨網域 XMLHttpRequest</h2> + +<p>現代瀏覽器支援跨網域（cross-site）請求並實作了網路應用程式工作小組（Web Applications (WebApps) Working Group）提出的<a href="/docs/Web/HTTP/Access_control_CORS">跨網域請求存取控制</a>標準。只要伺服器被設定為允許來自你的網路應用程式來源（origin）網域之請求，<code>XMLHttpRequest</code> 便能正常運作。否則，將會拋出一個 <code>INVALID_ACCESS_ERR</code> 例外。</p> + +<h2 id="避開快取">避開快取</h2> + +<p>有一個跨瀏覽器相容的避開快取方法，便是將時間戳記（timestamp）附加於 URL 後方，請確保加上了適當的「?」或「&」。例如：</p> + +<pre class="brush:plain">http://foo.com/bar.html -> http://foo.com/bar.html?12345 +http://foo.com/bar.html?foobar=baz -> http://foo.com/bar.html?foobar=baz&12345 +</pre> + +<p>由於本地快取的索引是基於 URL，加入時間戳記會導致每一個請求都會是唯一的，藉此避開快取。</p> + +<p>可以使用以下的程式碼來自動的調整 URL：</p> + +<pre class="brush:js">var oReq = new XMLHttpRequest(); + +oReq.open("GET", url + ((/\?/).test(url) ? "&" : "?") + (new Date()).getTime()); +oReq.send(null);</pre> + +<h2 id="安全性">安全性</h2> + +<p>{{fx_minversion_note(3, "Firefox 3 之前的版本允許在偏好設定中設定 <code>capability.policy.<policyname>.XMLHttpRequest.open</policyname></code> 為 <code>allAccess</code> 來讓指定的網域能夠跨網域存取。現已不再支援。")}}</p> + +<p>{{fx_minversion_note(5, "Firefox 5 之前的版本可以使用 <code>netscape.security.PrivilegeManager.enablePrivilege(\"UniversalBrowserRead\");</code> 來發送跨網域存取請求。現已不再支援，即使它不會有警告並且依然會顯示允許請求的權限對話框。")}}</p> + +<p>開啟跨網域指令碼（script）的建議方式是於 XMLHttpRequest 的回應中使用 <code>Access-Control-Allow-Origin</code> HTTP 標頭。</p> + +<h3 id="被中止的_XMLHttpRequest">被中止的 XMLHttpRequest</h3> + +<p>如果你發現 <code>XMLHttpRequest</code> 的 <code>status=0</code> 且 <code>statusText=null</code>，這代表請求並不被允許執行，其狀態為 <code><a href="https://xhr.spec.whatwg.org/#dom-xmlhttprequest-unsent">UNSENT（未送出）</a></code>。被中止的原因可能是因為 <a href="https://www.w3.org/TR/2010/CR-XMLHttpRequest-20100803/#xmlhttprequest-origin"><code>XMLHttpRequest</code> 物件所關聯的 origin（來源網域）值</a>（於 <code>XMLHttpRequest</code> 物件建立時自 <code>window.origin</code> 取得）在呼叫 <code>open()</code> 方法之前就已經被改變。這是可能發生的，例如在 <code>window</code> 的 <code>onunload</code> 事件觸發時送出 <code>XMLHttpRequest</code> 請求，預期的情況為：<code>XMLHttpRequest</code> 物件剛被建立，而目前的視窗尚未關閉，而最後發送請求（即呼叫了 <code>open()</code> 方法）的時間點是在此視窗失去了焦點並且另外的視窗取得焦點之間。要避開這個問題的最有效方法是在要被終止的（terminated）<code>window</code> 觸發 <code>unload</code> 事件時，於新的 <code>window</code> 的上註冊一個新的 <code>activate</code> 事件監聽器來發送請求。</p> + +<h2 id="使用_JavaScript_模組／XPCOM_元件中的_XMLHttpRequest">使用 JavaScript 模組／XPCOM 元件中的 XMLHttpRequest</h2> + +<p>自 <a href="/docs/Mozilla/JavaScript_code_modules/Using">JavaScript 模組</a> 或 XPCOM 元件實體化一個 <code>XMLHttpRequest</code> 物件在做法上會有些許不同；我們無法用 <code>XMLHttpRequest()</code> 建構式，因為此建構式並未在元件中定義，並會導致程式產生錯誤。較佳的方式是使用 XPCOM 元件的建構式。</p> + +<pre class="brush: js">const XMLHttpRequest = Components.Constructor("@mozilla.org/xmlextras/xmlhttprequest;1", + "nsIXMLHttpRequest"); +</pre> + +<p>在 Gecko 16 之前，存在著一個透過這種方式發送的請求會被無條件取消的臭蟲。若程式需要在 Gecko 15 或更早的版本上運作，可以從隱藏的 DOM window 中取得 <code>XMLHttpRequest()</code> 建構式。</p> + +<pre class="brush:js">const { XMLHttpRequest } = Components.classes["@mozilla.org/appshell/appShellService;1"] + .getService(Components.interfaces.nsIAppShellService) + .hiddenDOMWindow; +var oReq = new XMLHttpRequest();</pre> + +<h2 id="參見">參見</h2> + +<ol> + <li><a href="/docs/AJAX/Getting_Started">MDN AJAX 介紹</a></li> + <li><a href="/docs/Web/HTTP/Access_control_CORS">HTTP 存取控制</a></li> + <li><a href="/docs/How_to_check_the_security_state_of_an_XMLHTTPRequest_over_SSL">How to check the security state of an XMLHTTPRequest over SSL</a></li> + <li><a href="http://www.peej.co.uk/articles/rich-user-experience.html">XMLHttpRequest - REST and the Rich User Experience</a></li> + <li><a href="https://msdn.microsoft.com/library/ms535874">Microsoft documentation</a></li> + <li><a href="https://developer.apple.com/library/safari/documentation/AppleApplications/Conceptual/SafariJSProgTopics/Articles/XHR.html">Apple developers' reference</a></li> + <li><a href="http://jibbering.com/2002/4/httprequest.html">"Using the XMLHttpRequest Object" (jibbering.com)</a></li> + <li><a href="https://xhr.spec.whatwg.org/">The <code>XMLHttpRequest</code> object: WHATWG specification</a></li> +</ol> diff --git a/files/zh-tw/web/api/xmlhttprequest/withcredentials/index.html b/files/zh-tw/web/api/xmlhttprequest/withcredentials/index.html new file mode 100644 index 0000000000..e70f611ece --- /dev/null +++ b/files/zh-tw/web/api/xmlhttprequest/withcredentials/index.html @@ -0,0 +1,48 @@ +--- +title: XMLHttpRequest.withCredentials +slug: Web/API/XMLHttpRequest/withCredentials +translation_of: Web/API/XMLHttpRequest/withCredentials +--- +<div>{{APIRef('XMLHttpRequest')}}</div> + +<p><code><strong>XMLHttpRequest.withCredentials</strong></code> 屬性是一個 {{jsxref("Boolean")}} 型別，它指出無論是否使用 <code>Access-Control</code> 標頭在跨站的要求上，都應該使用像 Cookies、Authorization 標頭或 TLS 用戶端憑證來進行驗證。在相同來源的要求設定 <code>withCredentials</code> 沒有任何效果。</p> + +<p>In addition, this flag is also used to indicate when cookies are to be ignored in the response. The default is <code>false</code>. <code>XMLHttpRequest</code> from a different domain cannot set cookie values for their own domain unless <code>withCredentials</code> is set to <code>true</code> before making the request. The third-party cookies obtained by setting <code>withCredentials</code> to true will still honor same-origin policy and hence can not be accessed by the requesting script through <a href="/en-US/docs/Web/API/Document/cookie">document.cookie</a> or from response headers.</p> + +<div class="note"> +<p><strong>Note:</strong> 永遠不會影響到同源請求。</p> +</div> + +<div class="note"> +<p><strong>Note:</strong><strong> </strong><code>XMLHttpRequest</code> responses from a different domain <em>cannot</em> set cookie values for their own domain unless <code>withCredentials</code> is set to <code>true</code> before making the request, regardless of <code>Access-Control-</code> header values. </p> +</div> + +<h2 id="範例">範例</h2> + +<pre class="brush: js">var xhr = new XMLHttpRequest(); +xhr.open('GET', 'http://example.com/', true); +xhr.withCredentials = true; +xhr.send(null);</pre> + +<h2 id="規格">規格</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">規格</th> + <th scope="col">狀態</th> + <th scope="col">備註</th> + </tr> + <tr> + <td>{{SpecName('XMLHttpRequest', '#the-withcredentials-attribute')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td>WHATWG living standard</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + + + +<p>{{Compat("api.XMLHttpRequest.withCredentials")}}</p> diff --git a/files/zh-tw/web/api/xmlhttprequest/xmlhttprequest/index.html b/files/zh-tw/web/api/xmlhttprequest/xmlhttprequest/index.html new file mode 100644 index 0000000000..6459ef0c2a --- /dev/null +++ b/files/zh-tw/web/api/xmlhttprequest/xmlhttprequest/index.html @@ -0,0 +1,50 @@ +--- +title: XMLHttpRequest() +slug: Web/API/XMLHttpRequest/XMLHttpRequest +translation_of: Web/API/XMLHttpRequest/XMLHttpRequest +--- +<div>{{draft}}{{APIRef('XMLHttpRequest')}}</div> + +<p><span class="seoSummary"><code><strong>XMLHttpRequest()</strong></code> 建構式會建立一個新的 {{domxref("XMLHttpRequest")}} 物件。</span></p> + +<p>關於如何使用 <code>XMLHttpRequest</code> 物件的細節，請參照： <a class="internal" href="/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest">Using XMLHttpRequest</a>.</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">const <var>request</var> = new XMLHttpRequest(); +</pre> + +<h3 id="參數">參數</h3> + +<p>無。</p> + +<h3 id="回傳值">回傳值 </h3> + +<p>將回傳一個新的 {{domxref("XMLHttpRequest")}} 物件。{{domxref("XMLHttpRequest")}} 物件在呼叫{{domxref("XMLHttpRequest.send", "send()")}} 送出要求到伺服器之前，至少要藉著呼叫 {{domxref("XMLHttpRequest.open", "open()")}} 來準備好必需的設定。</p> + +<h2 id="非標準的_Firefox_語法">非標準的 Firefox 語法</h2> + +<p>Firefox 16 added a non-standard parameter to the constructor that can enable anonymous mode (see {{Bug("692677")}}). Setting the <code>mozAnon</code> flag to <code>true</code> effectively resembles the <a href="http://www.w3.org/TR/2012/WD-XMLHttpRequest-20120117/#dom-anonxmlhttprequest" title="see AnonXMLHttpRequest in the XMLHttpRequest specification"><code>AnonXMLHttpRequest()</code></a> constructor described in older versions of the XMLHttpRequest specification.</p> + +<pre class="syntaxbox">const <var>request</var> = new XMLHttpRequest(<var>paramsDictionary</var>);</pre> + +<h3 id="Parameters_non-standard">Parameters (non-standard)</h3> + +<dl> + <dt><code>objParameters</code> {{gecko_minversion_inline("16.0")}}</dt> + <dd>There are two flags you can set: + <dl> + <dt><code>mozAnon</code></dt> + <dd>Boolean: Setting this flag to <code>true</code> will cause the browser not to expose the {{Glossary("origin")}} and <a href="http://www.w3.org/TR/2012/WD-XMLHttpRequest-20120117/#user-credentials" title="Defintion of “User credentials” in the XMLHttpRequest specification.">user credentials</a> when fetching resources. Most important, this means that {{Glossary("Cookie", "cookies")}} will not be sent unless explicitly added using setRequestHeader.</dd> + <dt><code>mozSystem</code></dt> + <dd>Boolean: Setting this flag to <code>true</code> allows making cross-site connections without requiring the server to opt-in using {{Glossary("CORS")}}. <em>Requires setting <code>mozAnon: true</code>, i.e. this can't be combined with sending cookies or other user credentials. This only works in privileged (reviewed) apps ({{Bug("692677")}}); it does not work on arbitrary webpages loaded in Firefox</em></dd> + </dl> + </dd> +</dl> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest">Using XMLHttpRequest</a></li> + <li><a href="/en-US/docs/Web/API/XMLHttpRequest/HTML_in_XMLHttpRequest">HTML in XMLHttpRequest</a></li> +</ul> diff --git a/files/zh-tw/web/api/xmlhttprequesteventtarget/index.html b/files/zh-tw/web/api/xmlhttprequesteventtarget/index.html new file mode 100644 index 0000000000..41045ab17f --- /dev/null +++ b/files/zh-tw/web/api/xmlhttprequesteventtarget/index.html @@ -0,0 +1,111 @@ +--- +title: XMLHttpRequestEventTarget +slug: Web/API/XMLHttpRequestEventTarget +translation_of: Web/API/XMLHttpRequestEventTarget +--- +<p>{{APIRef("XMLHttpRequest")}}</p> + +<p><code>XMLHttpRequestEventTarget</code> 介面描述了一個 {{ domxref("XMLHttpRequest") }} 物件實體當中，所有可註冊事件處理器的屬性。</p> + +<p>{{InheritanceDiagram}}</p> + +<h2 id="屬性">屬性</h2> + +<dl> + <dt>{{ domxref("XMLHttpRequestEventTarget.onabort") }}</dt> + <dd>Contains the function to call when a request is aborted and the {{event('abort')}} event is received by this object.</dd> + <dt>{{ domxref("XMLHttpRequestEventTarget.onerror") }}</dt> + <dd>Contains the function to call when a request encounters an error and the {{event('error')}} event is received by this object.</dd> + <dt>{{ domxref("XMLHttpRequestEventTarget.onload") }}</dt> + <dd>Contains the function to call when an HTTP request returns after successfully fetching content and the {{event('load')}} event is received by this object.</dd> + <dt>{{ domxref("XMLHttpRequestEventTarget.onloadstart") }}</dt> + <dd>Contains the function that gets called when the HTTP request first begins loading data and the {{event('loadstart')}} event is received by this object.</dd> + <dt>{{ domxref("XMLHttpRequestEventTarget.onprogress") }}</dt> + <dd>Contains the function that is called periodically with information about the progress of the request and the {{event('progress')}} event is received by this object.</dd> + <dt>{{ domxref("XMLHttpRequestEventTarget.ontimeout") }}</dt> + <dd>Contains the function that is called if the event times out and the {{event("timeout")}} event is received by this object; this only happens if a timeout has been previously established by setting the value of the <code>XMLHttpRequest</code> object's <code>timeout</code> attribute.</dd> + <dt>{{ domxref("XMLHttpRequestEventTarget.onloadend") }}</dt> + <dd>Contains the function that is called when the load is completed, even if the request failed, and the {{event('loadend')}} event is received by this object.</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')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td>WHATWG living standard</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{CompatibilityTable}}</p> + +<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 (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>1</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("1.0")}}</td> + <td>7</td> + <td>{{CompatVersionUnknown}}</td> + <td>1.2</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>1.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p> </p> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{ domxref("XMLHttpRequest") }}</li> + <li><a href="/zh-TW/DOM/XMLHttpRequest/Using_XMLHttpRequest" title="Using XMLHttpRequest">Using XMLHttpRequest</a></li> +</ul> |