docs(events): add CustomEvent

ruanyf · ruanyf · commit 1f4b637a1a55 · 2018-05-03T15:05:20.000+08:00
diff --git a/chapters.yml b/chapters.yml
@@ -60,7 +60,7 @@
 - events/event.md: Event 对象
 - events/mouseevent.md: MouseEvent 接口，WheelEvent 接口
 - events/touchevent.md: Touch 接口，TouchList 接口，TouchEvent 接口
-- events/keyboardevent.md: KeyboardEvent 接口，InputEvent 接口
+- events/keyboardevent.md: KeyboardEvent 接口，InputEvent 接口，CustomEvent 接口
 - events/globaleventhandlers.md: GlobalEventHandlers 接口
 - bom/: 浏览器模型
 - bom/cookie.md: Cookie
diff --git a/docs/events/keyboardevent.md b/docs/events/keyboardevent.md
@@ -1,4 +1,4 @@
-# KeyboardEvent 接口，InputType 接口
+# KeyboardEvent 接口，InputType 接口，CustomEvent 接口
 
 ## KeyboardEvent 概述
 
@@ -163,3 +163,55 @@ function myFunction(e) {
 
 `InputEvent.dataTransfer`属性返回一个 DataTransfer 实例。该属性只在文本框接受粘贴内容（insertFromPaste）或拖拽内容（`insertFromDrop`）时才有效。
 
+## CustomEvent 接口
+
+CustomEvent 接口用于生成自定义的事件实例。那些浏览器预定义的事件，虽然可以手动生成，但是往往不能在事件上绑定数据。如果需要在触发事件的同时，传入指定的数据，就可以使用 CustomEvent 接口生成的自定义事件对象。
+
+浏览器原生提供`CustomEvent()`构造函数，用来生成 CustomEvent 事件实例。
+
+```javascript
+new CustomEvent(type, options)
+```
+
+`CustomEvent()`构造函数接受两个参数。第一个参数是字符串，表示事件的名字，这是必须的。第二个参数是事件的配置对象，这个参数是可选的。`CustomEvent`的配置对象除了接受 Event 事件的配置属性，只有一个自己的属性。
+
+- `detail`：表示事件的附带数据，默认为`null`。
+
+下面是一个例子。
+
+```javascript
+var event = new CustomEvent('build', { 'detail': 'hello' });
+
+function eventHandler(e) {
+  console.log(e.detail);
+}
+
+document.body.addEventListener('build', function (e) {
+  console.log(e.detail);
+});
+
+document.body.dispatchEvent(event);
+```
+
+上面代码中，我们手动定义了`build`事件。该事件触发后，会被监听到，从而输出该事件实例的`detail`属性（即字符串`hello`）。
+
+下面是另一个例子。
+
+```javascript
+var myEvent = new CustomEvent('myevent', {
+  detail: {
+    foo: 'bar'
+  },
+  bubbles: true,
+  cancelable: false
+});
+
+el.addEventListener('myevent', function (event) {
+  console.log('Hello ' + event.detail.foo);
+});
+
+el.dispatchEvent(myEvent);
+```
+
+上面代码也说明，CustomEvent 的事件实例，除了具有 Event 接口的实例属性，还具有`detail`属性。
+
