blob: 8977c22c9e30878027c45e1b59231415451928b8 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
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>
|
