blob: 3eea61b765e9e83350c99761f67911f703e2aec2 (
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
|
---
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>
{{Compat("api.EventTarget.dispatchEvent")}}
|
