aboutsummaryrefslogtreecommitdiff
path: root/files/zh-tw/web/guide/events
diff options
context:
space:
mode:
Diffstat (limited to 'files/zh-tw/web/guide/events')
-rw-r--r--files/zh-tw/web/guide/events/creating_and_triggering_events/index.html144
-rw-r--r--files/zh-tw/web/guide/events/event_handlers/index.html178
-rw-r--r--files/zh-tw/web/guide/events/index.html52
3 files changed, 374 insertions, 0 deletions
diff --git a/files/zh-tw/web/guide/events/creating_and_triggering_events/index.html b/files/zh-tw/web/guide/events/creating_and_triggering_events/index.html
new file mode 100644
index 0000000000..c198adaa5e
--- /dev/null
+++ b/files/zh-tw/web/guide/events/creating_and_triggering_events/index.html
@@ -0,0 +1,144 @@
+---
+title: 建立或觸發事件
+slug: Web/Guide/Events/Creating_and_triggering_events
+tags:
+ - Advanced
+ - DOM
+ - Guide
+ - JavaScript
+ - 事件
+translation_of: Web/Guide/Events/Creating_and_triggering_events
+---
+<p>本文介紹如何建立和觸發事件。</p>
+
+<h2 id="建立自定義事件">建立自定義事件</h2>
+
+<p>事件可以用 {{domxref("Event")}} constructor 建立,如下所示:</p>
+
+<pre class="brush: js">var event = new Event('build');
+
+// 監聽事件
+elem.addEventListener('build', function (e) { ... }, false);
+
+// 觸發事件
+elem.dispatchEvent(event);</pre>
+
+<p>除了 Internet Explorer 以外,大多數的瀏覽器都支持這個 constructor 。若要能夠支援 Internet Explore 的更詳細的方法,可以參考段落《<a href="#早期的做法" title="早期的作法">早期的做法</a>》。</p>
+
+<h3 id="增加自定義的資料--CustomEvent()">增加自定義的資料--CustomEvent()</h3>
+
+<p>要在事件的 object 追加其他資料,能使用 {{domxref("CustomEvent")}} 介面。它有 <u><strong>detail</strong></u> 屬性,可以用來傳送自訂資料。<br>
+ <span style="line-height: 1.5;">舉例來說,可以以下面方式建立事件:</span></p>
+
+<pre class="brush: js">var event = new CustomEvent('build', { 'detail': elem.dataset.time });</pre>
+
+<p>它可以讓你傳送自訂資料到事件的監聽器:</p>
+
+<pre class="brush: js">function eventHandler(e) {
+ log('The time is: ' + e.detail);
+}
+</pre>
+
+<h3 id="早期的做法">早期的做法</h3>
+
+<p>早期建立事件的方式參考了 Java 的 API 。下為一個早期作法的例子:</p>
+
+<pre class="brush: js">// 建立事件
+var event = document.createEvent('Event');
+
+// 設定事件名稱為 “build” 。
+event.initEvent('build', true, true);
+
+// 監聽事件
+elem.addEventListener('build', function (e) {
+ // e.target matches elem
+}, false);
+
+// 事件對象可以是任一 HTML 元素或是 EventTarget 。
+elem.dispatchEvent(event);
+
+</pre>
+
+<h2 id="觸發自定義事件">觸發自定義事件</h2>
+
+<p>下面的例子演示了一個複選框藉由 DOM 的 methods 模擬一次點擊(換言之,讓程式執行一次「點擊事件」。)。 <a class="external" href="http://developer.mozilla.org/samples/domref/dispatchEvent.html">觀看實例</a>。</p>
+
+<pre class="brush: js">function simulateClick() {
+ var event = new MouseEvent('click', {
+ 'view': window,
+ 'bubbles': true,
+ 'cancelable': true
+ });
+ var cb = document.getElementById('checkbox');
+ var canceled = !cb.dispatchEvent(event);
+ if (canceled) {
+ // A handler called preventDefault.
+ alert("canceled");
+ } else {
+ // None of the handlers called preventDefault.
+ alert("not canceled");
+ }
+}</pre>
+
+<h2 id="Browser_compatibility" name="Browser_compatibility" style="line-height: 30px; font-size: 2.14285714285714rem;">瀏覽器的支援度</h2>
+
+<h2 id="sect1"> </h2>
+
+<p>{{ CompatibilityTable() }}</p>
+
+<div id="compat-desktop">
+<table class="compat-table">
+ <tbody>
+ <tr>
+ <th style="line-height: 16px;">Feature</th>
+ <th style="line-height: 16px;">Chrome</th>
+ <th style="line-height: 16px;">Firefox (Gecko)</th>
+ <th style="line-height: 16px;">Edge</th>
+ <th style="line-height: 16px;">Internet Explorer</th>
+ <th style="line-height: 16px;">Opera</th>
+ <th style="line-height: 16px;">Safari (WebKit)</th>
+ </tr>
+ <tr>
+ <td><code>Event()</code> constructor</td>
+ <td>15</td>
+ <td>11</td>
+ <td>{{CompatVersionUnknown}}</td>
+ <td>{{CompatNo}}</td>
+ <td>11.60</td>
+ <td>6</td>
+ </tr>
+ </tbody>
+</table>
+</div>
+
+<div id="compat-mobile">
+<table class="compat-table">
+ <tbody>
+ <tr>
+ <th style="line-height: 16px;">Feature</th>
+ <th style="line-height: 16px;">Android</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>
+ </tr>
+ <tr>
+ <td>Basic support</td>
+ <td>{{ CompatUnknown() }}</td>
+ <td>{{ CompatUnknown() }}</td>
+ <td>{{ CompatUnknown() }}</td>
+ <td>{{ CompatUnknown() }}</td>
+ <td>6</td>
+ </tr>
+ </tbody>
+</table>
+</div>
+
+<h2 id="延伸閱讀">延伸閱讀</h2>
+
+<ul>
+ <li>{{domxref("document.createEvent()")}}</li>
+ <li>{{domxref("Event.initEvent()")}}</li>
+ <li>{{domxref("EventTarget.dispatchEvent()")}}</li>
+ <li>{{domxref("EventTarget.addEventListener()")}}</li>
+</ul>
diff --git a/files/zh-tw/web/guide/events/event_handlers/index.html b/files/zh-tw/web/guide/events/event_handlers/index.html
new file mode 100644
index 0000000000..519ac8bf90
--- /dev/null
+++ b/files/zh-tw/web/guide/events/event_handlers/index.html
@@ -0,0 +1,178 @@
+---
+title: DOM on-event 處理器
+slug: Web/Guide/Events/Event_handlers
+translation_of: Web/Guide/Events/Event_handlers
+---
+<p><span class="seoSummary">Web 平台提供了多種獲得 <a href="/zh-TW/docs/Web/Events">DOM 事件</a>通知的方式。兩種常見的風格為:通用的 {{domxref("EventTarget.addEventListener", "addEventListener()")}} 及一組特定的 <em><strong>on-event</strong></em> 處理器。</span>本頁聚焦在後者如何運作的細節。</p>
+
+<h3 id="註冊_on-event_處理器">註冊 <em>on-event</em> 處理器</h3>
+
+<p><em><strong>on-event</strong></em> 處理器為一群由 DOM 元素提供的屬性({{Glossary("property")}}),用來協助管理元素要如何應對事件。元素可以是具互動性的(如:links、buttons、images、forms)或非互動性的(如頁面基礎 document)。事件為一個操作,像是點擊(clicked)、偵測按下按鍵(pressed keys)、取得焦點(focus)等。on-event 處理器通常是根據它被設計來應對的事件,例如 <code>onclick</code>、<code>onkeypress</code>、<code>onfocus</code> 等等。</p>
+
+<p>你可以使用兩種不同的方式來為一個物件的特定事件(例如:{{event("click")}})指定一個 <code>on&lt;...&gt;</code> 事件處理器:</p>
+
+<ul>
+ <li>在元素上使用一個名稱為 <code>on<em>{eventtype}</em></code> 的 HTML 標籤屬性({{Glossary("attribute")}}),例如:<br>
+ <code>&lt;button <u>onclick="return handleClick(event);"</u>&gt;</code>,</li>
+ <li>或藉由設定相對應的 JavaScript 屬性({{Glossary("property/JavaScript", "property")}}),例如:<br>
+ <code>document.getElementById("mybutton")<u>.onclick = function(event) { ... }</u></code>.</li>
+</ul>
+
+<p>Note that each object can have <strong>only one</strong> <em>on-event</em> handler for a given event (though that handler could call multiple sub-handlers). This is why {{domxref("EventTarget.addEventListener", "addEventListener()")}} is often the better way to get notified of events, especially when wishing to apply various event handlers independently from each other, even for the same event and/or to the same element.</p>
+
+<p>Also note that <em>on-event</em> handlers are called automatically, not at the programmer's will (although you can, like <code>mybutton.onclick(myevent); ) </code>since they serve more as placeholders to which a real handler function can be <strong>assigned</strong>.</p>
+
+<h3 id="非元素物件">非元素物件</h3>
+
+<p>Event handlers can also be set using properties on many non-element objects that generate events, including {{ domxref("window") }}, {{ domxref("document") }}, {{ domxref("XMLHttpRequest") }}, and others, for example:</p>
+
+<pre>xhr.onprogress = function() { ... }</pre>
+
+<h2 id="細節">細節</h2>
+
+<h3 id="HTML_的_on&lt;...>_屬性值及對應的_JavaScript_屬性">HTML 的 on&lt;...&gt; 屬性值及對應的 JavaScript 屬性</h3>
+
+<p>A handler registered via an <code>on&lt;...&gt;</code> attribute will be available via the corresponding <code>on&lt;...&gt;</code> property, but not the other way around:</p>
+
+<pre class="brush: html">&lt;div id="a" onclick="alert('old')"&gt;Open the Developer Tools Console to see the output.&lt;/div&gt;
+
+&lt;script&gt;
+window.onload = function () {
+ var div = document.getElementById("a");
+ console.log("Attribute reflected as a property: ", div.onclick.toString());
+ // Prints: function onclick(event) { alert('old') }
+ div.onclick = function() { alert('new') };
+ console.log("Changed property to: ", div.onclick.toString());
+ // Prints: function () { alert('new') }
+ console.log("Attribute value is unchanged: ", div.getAttribute("onclick"));
+ // Prints: alert('old')
+}
+&lt;/script&gt;</pre>
+
+<p>For historical reasons, some attributes/properties on the {{HTMLElement("body")}} and {{HTMLElement("frameset")}} elements actually set event handlers on their parent {{domxref("Window")}} object. (The HTML specification names these: <code>onblur</code>, <code>onerror</code>, <code>onfocus</code>, <code>onload</code>, <code>onscroll</code>.)</p>
+
+<h3 id="事件處理器的參數、this_綁定及回傳值">事件處理器的參數、<code>this</code> 綁定及回傳值</h3>
+
+<p>當一個事件處理被定義成為一個 <strong>HTML </strong>的屬性時,給定的程式碼會被包成一個具有下列參數的函式:</p>
+
+<ul>
+ <li><code>event</code> - 除了{{domxref("GlobalEventHandlers.onerror", "onerror")}}的事件以外,其他所有的事件都會有此參數。</li>
+ <li><code>event</code>, <code>source</code>, <code>lineno</code>, <code>colno</code>, 還有專為 {{domxref("GlobalEventHandlers.onerror", "onerror")}} 事件處理的 <code>error</code> 。請注意: <code>event</code> 參數實際上擁有以字串形式呈現的錯誤訊息。</li>
+</ul>
+
+<p>當事件處理函式被觸發時,處理函式中的關鍵字: <code>this</code> 被設定成為註冊這個事件處理函式的DOM 元件。 請參閱 <a href="/en-US/docs/Web/JavaScript/Reference/Operators/this#In_an_in%E2%80%93line_event_handler">this 關鍵字說明</a> 獲得更多細節。</p>
+
+<p>The return value from the handler determines if the event is canceled. The specific handling of the return value depends on the kind of event, for details see <a href="https://html.spec.whatwg.org/multipage/webappapis.html#the-event-handler-processing-algorithm">"The event handler processing algorithm" in the HTML specification</a>.</p>
+
+<h3 id="當事件處理器被調用">當事件處理器被調用</h3>
+
+<p>TBD (non-capturing listener)</p>
+
+<h3 id="術語">術語</h3>
+
+<p>The term <strong>event handler</strong> may be used to refer to:</p>
+
+<ul>
+ <li>any function or object registered to be notified of events,</li>
+ <li>or, more specifically, to the mechanism of registering event listeners via <code>on...</code> attributes in HTML or properties in web APIs, such as <code>&lt;button onclick="alert(this)"&gt;</code> or <code>window.onload = function() { /* ... */ }</code>.</li>
+</ul>
+
+<p>When discussing the various methods of listening to events,</p>
+
+<ul>
+ <li><strong>event listener</strong> refers to a function or object registered via {{domxref("EventTarget.addEventListener()")}},</li>
+ <li>whereas <strong>event handler</strong> refers to a function registered via <code>on...</code> attributes or properties.</li>
+</ul>
+
+<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', 'webappapis.html#event-handler-attributes', 'event handlers')}}</td>
+ <td>{{Spec2('HTML WHATWG')}}</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>{{SpecName('HTML5 W3C', 'webappapis.html#event-handler-attributes', 'event handlers')}}</td>
+ <td>{{Spec2('HTML5 W3C')}}</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>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 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>
+
+<h3 id="Event_handler_changes_in_Firefox_9">Event handler changes in Firefox 9</h3>
+
+<p>In order to better match the specifications, and improve cross-browser compatibility, the way event handlers were implemented at a fundamental level changed in Gecko 9.0 {{ geckoRelease("9.0") }}.</p>
+
+<p>Specifically, in the past, event handlers were not correctly implemented as standard IDL attributes. In Gecko 9.0, this was changed. Because of this, certain behaviors of event handlers in Gecko have changed. In particular, they now behave in all the ways standard IDL attributes behave. In most cases, this shouldn't affect web or add-on content at all; however, there are a few specific things to watch out for.</p>
+
+<h4 id="Detecting_the_presence_of_event_handler_properties">Detecting the presence of event handler properties</h4>
+
+<p>You can now detect the presence of an event handler property (that is, for example, <code>onload</code>), using the JavaScript <a href="/en-US/JavaScript/Reference/Operators/in" title="en/JavaScript/Reference/Operators/in"><code>in</code></a> operator. For example:</p>
+
+<pre class="brush: js">if ("onsomenewfeature" in window) {
+ /* do something amazing */
+}
+</pre>
+
+<h4 id="Event_handlers_and_prototypes">Event handlers and prototypes</h4>
+
+<p>You can't set or access the values of any IDL-defined attributes on DOM prototype objects; that means you can't, for example, change <code>Window.prototype.onload</code> anymore. In the past, event handlers (<code>onload</code>, etc.) weren't implemented as IDL attributes in Gecko, so you were able to do this for those. Now you can't. This improves compatibility.</p>
diff --git a/files/zh-tw/web/guide/events/index.html b/files/zh-tw/web/guide/events/index.html
new file mode 100644
index 0000000000..4484986b66
--- /dev/null
+++ b/files/zh-tw/web/guide/events/index.html
@@ -0,0 +1,52 @@
+---
+title: Event developer guide
+slug: Web/Guide/Events
+tags:
+ - DOM
+ - Event
+ - Guide
+ - NeedsTranslation
+ - NeedsUpdate
+ - TopicStub
+translation_of: Web/Guide/Events
+---
+<p>{{draft()}}</p>
+
+<p>Events refers both to a design pattern used for the asynchronous handling of various incidents which occur in the lifetime of a web page and to the naming, characterization, and use of a large number of incidents of different types.</p>
+
+<p>The <a href="/en-US/docs/Web/Guide/API/DOM/Events/Overview_of_Events_and_Handlers">overview page</a> provides an introduction to the design pattern and a summary of the types of incidents which are defined and reacted to by modern web browsers.</p>
+
+<p>The <a href="/en-US/docs/Web/Guide/API/DOM/Events/Creating_and_triggering_events">custom events page</a> describes how the event code design pattern can be used in custom code to define new event types emitted by user objects, register listener functions to handle those events, and trigger the events in user code.</p>
+
+<p>The remaining pages describe how to use events of different kinds defined by web browsers. Unfortunately, these events have been defined piece by piece as web browsers have evolved so that there is no satisfying systematic characterization of the events built-in or defined by modern web browsers.</p>
+
+<p>The <strong>device</strong> on which the web browser is running can trigger events, for example due to a change in its position and orientation in the real world, as discussed partially by the <a href="/en-US/docs/Web/Guide/API/DOM/Events/Orientation_and_motion_data_explained">page on orientation coordinate systems</a> and the <a href="/en-US/docs/Web/Guide/API/DOM/Events/Using_device_orientation_with_3D_transforms">page on the use of 3D transforms</a>. That is different, but similar, to the change in device vertical orientation.</p>
+
+<p>The <strong>window</strong> in which the browser is displayed can trigger events; for example, change size if the user maximizes the window or otherwise changes it.</p>
+
+<p>The <strong>process</strong> loading of a web page can trigger events in response to the completion of different steps in the downloading, parsing, and rendering of the web page for display to the user.</p>
+
+<p>The <strong>user interaction</strong> with the web page contents can trigger events. The events triggered by user interaction evolved during the early years of browser design and include a complicated system defining the sequence in which events will be called and the manner in which that sequence can be controlled. The different types of user interaction-driven events include:</p>
+
+<ul>
+ <li>the original 'click' event,</li>
+ <li>mouse events,</li>
+ <li><a href="/en-US/docs/Web/Guide/API/DOM/Events/Mouse_gesture_events">mouse gesture events</a>, and</li>
+ <li>both <a href="/en-US/docs/Web/Guide/API/DOM/Events/Touch_events">touch events</a> and the earlier <a href="/en-US/docs/Web/Guide/API/DOM/Events/Touch_events_(Mozilla_experimental)">mozilla experimental touch events</a>, now deprecated.</li>
+</ul>
+
+<p>The <strong>modification of the web page</strong> in structure or content might trigger some events, as explained in the <a href="/en-US/docs/Web/Guide/API/DOM/Events/Mutation_events">mutation events page</a>, but the use of these events has been deprecated in favour of the lighter <a href="/en-US/docs/Web/API/MutationObserver">Mutation Observer</a> approach.</p>
+
+<p>The <strong>media streams</strong> embedded in the HTML documents might trigger some events, as explained in the <a href="/en-US/docs/Web/Guide/API/DOM/Events/Media_events">media events</a> page.</p>
+
+<p>The <strong>network requests</strong> made by a web page might trigger some events.</p>
+
+<p>There are many other sources of events defined by web browsers for which pages are not yet available in this guide.</p>
+
+<div class="note">
+<p>Note: This Event Developer Guide needs substantial work. The structure needs to be reorganized and the pages rewritten. Our hope is that everything you need to know about events will go under here.</p>
+</div>
+
+<h2 id="文件">文件</h2>
+
+<p>{{LandingPageListSubpages}}</p>