Skip to content

Commit 3e1a5b6

Browse files
ruanyfruanyf
committed
docs(event/eventtarget): edit text
1 parent 5d7484c commit 3e1a5b6

1 file changed

Lines changed: 26 additions & 30 deletions

File tree

‎docs/events/eventtarget.md‎

Lines changed: 26 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,11 @@
22

33
事件的本质是程序各个组成部分之间的一种通信方式，也是异步编程的一种实现。DOM 支持大量的事件，本章开始介绍 DOM 的事件编程。
44

5+
介绍具体的事件之前，先来看看如何让 DOM 节点监听事件。
6+
57
## 概述
68

7-
DOM 的事件操作（监听和触发），都定义在`EventTarget`接口。所有节点对象都部署了这个接口，其他一些需要事件通信的浏览器内置对象（比如，`XMLHttpRequest`、`AudioNode`、`AudioContext`）也部署了这个接口。
9+
DOM 节点的事件操作（监听和触发），都定义在`EventTarget`接口。所有节点对象都部署了这个接口，其他一些需要事件通信的浏览器内置对象（比如，`XMLHttpRequest`、`AudioNode`、`AudioContext`）也部署了这个接口。
810

911
该接口主要提供三个实例方法。
1012

@@ -17,24 +19,16 @@ DOM 的事件操作（监听和触发），都定义在`EventTarget`接口。所
1719
`EventTarget.addEventListener()`用于在当前节点或对象上（即部署了 EventTarget 接口的对象），定义一个特定事件的监听函数。一旦这个事件发生，就会执行监听函数。该方法没有返回值。
1820

1921
```javascript
20-
targent.addEventListener(type, listener[, options]);
21-
// 或者
2222
target.addEventListener(type, listener[, useCapture]);
2323
```
2424

25-
该方法接受三个参数，前两个参数的含义如下。
25+
该方法接受三个参数。
2626

2727
- `type`：事件名称，大小写敏感。
2828
- `listener`：监听函数。事件发生时，会调用该监听函数。
29+
- `useCapture`：布尔值，如果设为`true`，表示监听函数将在捕获阶段（capture）触发（参见后文《事件的传播》部分）。该参数可选，默认值为`false`（监听函数只在冒泡阶段被触发）。
2930

30-
第三个参数有两种形式。如果是一个对象`options`，表示监听器的配置对象，用来对监听行为进行配置，有以下属性。
31-
32-
- `capture`：布尔值，如果设为`true`，表示监听函数在捕获阶段触发，默认为`false`，在冒泡阶段触发。
33-
- `once`：布尔值，如果设为`true`，表示监听函数触发后，只执行一次就会被移除。同样事件再次发生时，该监听函数将不存在。该属性默认值为`false`。
34-
- `passive`：布尔值，设为`true`时，表示监听函数不会调用`preventDefault()`阻止浏览器的默认行为，如果调用这个函数，将没有任何效果，并且控制台会打印一条报错信息。这个属性默认值为`false`。
35-
- `signal`：该属性的值为一个 AbortSignal 对象，为监听器设置了一个信号通道，用来在需要时发出信号，移除监听函数。
36-
37-
第三个参数如果是一个布尔值`useCapture`，则表示监听函数是否在捕获阶段（capture）触发（参见后文《事件的传播》部分）。该参数可选，默认值为`false`（监听函数只在冒泡阶段被触发）。下面是一个例子。
31+
下面是一个例子。
3832

3933
```javascript
4034
function hello() {
@@ -45,11 +39,11 @@ var button = document.getElementById('btn');
4539
button.addEventListener('click', hello, false);
4640
```
4741

48-
上面代码中，`button`节点的`addEventListener`方法绑定`click`事件的监听函数`hello`，该函数只在冒泡阶段触发。
42+
上面代码中，`button`节点的`addEventListener()`方法绑定`click`事件的监听函数`hello()`，该函数只在冒泡阶段触发。
4943

5044
关于参数，有两个地方需要注意。
5145

52-
首先，第二个参数除了监听函数，还可以是一个具有`handleEvent`方法的对象。
46+
首先，第二个参数除了监听函数，还可以是一个具有`handleEvent`方法的对象，效果与监听函数一样。
5347

5448
```javascript
5549
buttonElement.addEventListener('click', {
@@ -59,23 +53,24 @@ buttonElement.addEventListener('click', {
5953
});
6054
```
6155

62-
上面代码中，`addEventListener`方法的第二个参数，就是一个具有`handleEvent`方法的对象。
56+
上面代码中，`addEventListener()`方法的第二个参数，就是一个具有`handleEvent()`方法的对象。
6357

64-
其次，第三个参数除了布尔值`useCapture`，还可以是一个属性配置对象。该对象有以下属性。
58+
其次，第三个参数除了布尔值`useCapture`，还可以是一个监听器配置对象，定制事件监听行为。该对象有以下属性。
6559

66-
> - `capture`：布尔值，表示该事件是否在`捕获阶段`触发监听函数。
67-
> - `once`：布尔值，表示监听函数是否只触发一次，然后就自动移除。
68-
> - `passive`：布尔值，表示监听函数不会调用事件的`preventDefault`方法。如果监听函数调用了，浏览器将忽略这个要求，并在监控台输出一行警告。
60+
> - `capture`：布尔值，如果设为`true`，表示监听函数在捕获阶段触发，默认为`false`，在冒泡阶段触发。
61+
> - `once`：布尔值，如果设为`true`，表示监听函数执行一次就会自动移除，后面将不再监听该事件。该属性默认值为`false`。
62+
> - `passive`：布尔值，设为`true`时，表示禁止监听函数调用`preventDefault()`方法。如果调用了，浏览器将忽略这个要求，并在控制台输出一条警告。该属性默认值为`false`。
63+
> - `signal`：该属性的值为一个 AbortSignal 对象，为监听器设置了一个信号通道，用来在需要时发出信号，移除监听函数。
6964
70-
如果希望事件监听函数只执行一次，可以打开属性配置对象的`once`属性。
65+
下面是`once`属性的例子，让监听函数只执行一次。
7166

7267
```javascript
7368
element.addEventListener('click', function (event) {
7469
// 只执行一次的代码
7570
}, {once: true});
7671
```
7772

78-
`addEventListener`方法可以为针对当前对象的同一个事件，添加多个不同的监听函数。这些函数按照添加顺序触发，即先添加先触发。如果为同一个事件多次添加同一个监听函数，该函数只会执行一次，多余的添加将自动被去除（不必使用`removeEventListener`方法手动去除）。
73+
`addEventListener()`方法可以为针对当前对象的同一个事件，添加多个不同的监听函数。这些函数按照添加顺序触发，即先添加先触发。如果为同一个事件多次添加同一个监听函数，该函数只会执行一次，多余的添加将自动被去除（不必使用`removeEventListener()`方法手动去除）。
7974

8075
```javascript
8176
function hello() {
@@ -116,40 +111,40 @@ para.addEventListener('click', function (e) {
116111

117112
## EventTarget.removeEventListener()
118113

119-
`EventTarget.removeEventListener`方法用来移除`addEventListener`方法添加的事件监听函数。该方法没有返回值。
114+
`EventTarget.removeEventListener()`方法用来移除`addEventListener()`方法添加的事件监听函数。该方法没有返回值。
120115

121116
```javascript
122117
div.addEventListener('click', listener, false);
123118
div.removeEventListener('click', listener, false);
124119
```
125120

126-
`removeEventListener`方法的参数，与`addEventListener`方法完全一致。它的第一个参数“事件类型”，大小写敏感。
121+
`removeEventListener()`方法的参数，与`addEventListener()`方法完全一致。它的第一个参数“事件类型”，大小写敏感。
127122

128-
注意，`removeEventListener`方法移除的监听函数，必须是`addEventListener`方法添加的那个监听函数，而且必须在同一个元素节点，否则无效。
123+
注意，`removeEventListener()`方法移除的监听函数，必须是`addEventListener()`方法添加的那个监听函数，而且必须在同一个元素节点，否则无效。
129124

130125
```javascript
131126
div.addEventListener('click', function (e) {}, false);
132127
div.removeEventListener('click', function (e) {}, false);
133128
```
134129

135-
上面代码中，`removeEventListener`方法无效，因为监听函数不是同一个匿名函数。
130+
上面代码中，`removeEventListener()`方法无效，因为监听函数不是同一个匿名函数。
136131

137132
```javascript
138133
element.addEventListener('mousedown', handleMouseDown, true);
139134
element.removeEventListener("mousedown", handleMouseDown, false);
140135
```
141136

142-
上面代码中，`removeEventListener`方法也是无效的，因为第三个参数不一样。
137+
上面代码中，`removeEventListener()`方法也是无效的，因为第三个参数不一样。
143138

144139
## EventTarget.dispatchEvent()
145140

146-
`EventTarget.dispatchEvent`方法在当前节点上触发指定事件，从而触发监听函数的执行。该方法返回一个布尔值，只要有一个监听函数调用了`Event.preventDefault()`，则返回值为`false`，否则为`true`。
141+
`EventTarget.dispatchEvent()`方法在当前节点上触发指定事件，从而触发监听函数的执行。该方法返回一个布尔值，只要有一个监听函数调用了`Event.preventDefault()`，则返回值为`false`，否则为`true`。
147142

148143
```javascript
149144
target.dispatchEvent(event)
150145
```
151146

152-
`dispatchEvent`方法的参数是一个`Event`对象的实例（详见《Event 对象》章节）。
147+
`dispatchEvent()`方法的参数是一个`Event`对象的实例（详见《Event 对象》章节）。
153148

154149
```javascript
155150
para.addEventListener('click', hello, false);
@@ -159,9 +154,9 @@ para.dispatchEvent(event);
159154

160155
上面代码在当前节点触发了`click`事件。
161156

162-
如果`dispatchEvent`方法的参数为空，或者不是一个有效的事件对象，将报错。
157+
如果`dispatchEvent()`方法的参数为空，或者不是一个有效的事件对象，将报错。
163158

164-
下面代码根据`dispatchEvent`方法的返回值，判断事件是否被取消了。
159+
下面代码根据`dispatchEvent()`方法的返回值，判断事件是否被取消了。
165160

166161
```javascript
167162
var canceled = !cb.dispatchEvent(event);
@@ -171,3 +166,4 @@ if (canceled) {
171166
console.log('事件未取消');
172167
}
173168
```
169+

0 commit comments

Comments
 (0)