docs(events): add KeyboardEvent

ruanyf · ruanyf · commit 85eba7cd66e7 · 2018-05-01T13:38:23.000+08:00
diff --git a/chapters.yml b/chapters.yml
@@ -60,6 +60,7 @@
 - events/event.md: Event 对象
 - events/mouseevent.md: MouseEvent 接口，WheelEvent 接口
 - events/touchevent.md: Touch 接口，TouchList 接口，TouchEvent 接口
+- events/keyboardevent.md: KeyboardEvent 接口
 - events/globaleventhandlers.md: GlobalEventHandlers 接口
 - bom/: 浏览器模型
 - bom/cookie.md: Cookie
diff --git a/docs/events/event-type.md b/docs/events/event-type.md
@@ -0,0 +1,56 @@
+# 事件种类
+
+## 鼠标事件
+
+- click
+- dblclick
+- mouseup
+- mousedown
+
+## 触摸事件
+
+触摸引发的事件，有以下几种。可以通过`TouchEvent.type`属性，查看到底发生的是哪一种事件。
+
+- `touchstart`：用户开始触摸时触发，它的`target`属性返回发生触摸的元素节点。
+- `touchend`：用户不再接触触摸屏时（或者移出屏幕边缘时）触发，它的`target`属性与`touchstart`事件一致的，就是开始触摸时所在的元素节点。它的`changedTouches`属性返回一个`TouchList`实例，包含所有不再触摸的触摸点（即`Touch`实例对象）。
+- `touchmove`：用户移动触摸点时触发，它的`target`属性与`touchstart`事件一致。如果触摸的半径、角度、力度发生变化，也会触发该事件。
+- `touchcancel`：触摸点取消时触发，比如在触摸区域跳出一个情态窗口（modal window）、触摸点离开了文档区域（进入浏览器菜单栏）、用户的触摸点太多，超过了支持的上限（自动取消早先的触摸点）。
+
+下面是一个例子。
+
+```javascript
+var el = document.getElementsByTagName('canvas')[0];
+el.addEventListener('touchstart', handleStart, false);
+el.addEventListener('touchmove', handleMove, false);
+
+function handleStart(evt) {
+  evt.preventDefault();
+  var touches = evt.changedTouches;
+  for (var i = 0; i < touches.length; i++) {
+    console.log(touches[i].pageX, touches[i].pageY);
+  }
+}
+
+function handleMove(evt) {
+  evt.preventDefault();
+  var touches = evt.changedTouches;
+  for (var i = 0; i < touches.length; i++) {
+    var touch = touches[i];
+    console.log(touch.pageX, touch.pageY);
+  }
+}
+```
+
+## 键盘事件
+
+- keydown
+- keypress
+- keyup
+
+## 焦点事件
+
+- focus
+- blur
+- focusin
+- focusout
+
diff --git a/docs/events/globaleventhandlers.md b/docs/events/globaleventhandlers.md
@@ -186,13 +186,30 @@ element.ondragEnd = function (ev) {
 }
 ```
 
-## 触摸相关事件
+## 触摸事件的相关属性
+
+触摸事件的相关属性有四个。
 
 - GlobalEventHandlers.ontouchcancel
 - GlobalEventHandlers.ontouchend
 - GlobalEventHandlers.ontouchmove
 - GlobalEventHandlers.ontouchstart
 
+下面是一个例子。
+
+```javascript
+/* HTML 代码如下
+  <div id="target1"> 触摸这里 </div>
+*/
+
+function startTouch(event) {
+  // ...
+}
+
+var el=document.getElementById('target1');
+el.ontouchstart = startTouch;
+```
+
 ## 特定元素的属性
 
 ### GlobalEventHandlers.oncancel，GlobalEventHandlers.onclose
diff --git a/docs/events/keyboardevent.md b/docs/events/keyboardevent.md
@@ -0,0 +1,111 @@
+# KeyboardEvent 接口
+
+## KeyboardEvent 概述
+
+`KeyboardEvent`接口用来描述用户与键盘的互动。这个接口继承了`Event`接口，并且定义了自己的实例属性和实例方法。
+
+浏览器原生提供`KeyboardEvent`构造函数，用来新建键盘事件的实例。
+
+```javascript
+new KeyboardEvent(type, options)
+```
+
+`KeyboardEvent`构造函数接受两个参数。第一个参数是字符串，表示事件类型；第二个参数是一个事件配置对象，该参数可选。除了`Event`接口提供的属性，还可以配置以下字段，它们都是可选。
+
+- `key`：字符串，当前按下的键，默认为空字符串。
+- `code`：字符串，表示当前按下的键的字符串形式，默认为空字符串。
+- `location`：整数，当前按下的键的位置，默认为`0`。
+- `ctrlKey`：布尔值，是否按下 Ctrl 键，默认为`false`。
+- `shiftKey`：布尔值，是否按下 Shift 键，默认为`false`。
+- `altKey`：布尔值，是否按下 Alt 键，默认为`false`。
+- `metaKey`：布尔值，是否按下 Meta 键，默认为`false`。
+- `repeat`：布尔值，是否重复按键，默认为`false`。
+
+## KeyboardEvent 的实例属性
+
+### KeyboardEvent.altKey，KeyboardEvent.metaKey.ctrlKey，KeyboardEvent.metaKey，KeyboardEvent.shiftKey
+
+以下属性都是只读属性，返回一个布尔值，表示是否按下对应的键。
+
+- `KeyboardEvent.altKey`：是否按下 Alt 键
+- `KeyboardEvent.ctrlKey`：是否按下 Ctrl 键
+- `KeyboardEvent.metaKey`：是否按下 meta 键（Mac 系统是一个四瓣的小花，Windows 系统是 windows 键）
+- `KeyboardEvent.shiftKey`：是否按下 Shift 键
+
+下面是一个示例。
+
+```javascript
+function showChar(e){
+  console.log("ALT: " + e.altKey);
+  console.log("CTRL: " + e.ctrlKey);
+  console.log("Meta: " + e.metaKey);
+  console.log("Meta: " + e.shiftKey);
+}
+
+document.body.addEventListener('click', showChar, false);
+```
+
+### KeyboardEvent.code
+
+`KeyboardEvent.code`属性返回一个字符串，表示当前按下的键的字符串形式。该属性只读。
+
+下面是一些常用键的字符串形式，其他键请查[文档](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code#Code_values)。
+
+- 数字键0 - 9：返回`digital0` - `digital9`
+- 字母键A - z：返回`KeyA` - `KeyZ`
+- 功能键F1 - F12：返回 `F1` - `F12`
+- 方向键：返回`ArrowDown`、`ArrowUp`、`ArrowLeft`、`ArrowRight`
+- Alt 键：返回`AltLeft`或`AltRight`
+- Shift 键：返回`ShiftLeft`或`ShiftRight`
+- Ctrl 键：返回`ControLeft`或`ControlRight`
+
+### KeyboardEvent.key
+
+`KeyboardEvent.key`属性返回一个字符串，表示按下的键名。该属性只读。
+
+如果按下的键代表可打印字符，则返回这个字符，比如数字、字母。
+
+如果按下的键代表不可打印的特殊字符，则返回预定义的键值，比如 Backspace，Tab，Enter，Shift，Control，Alt，CapsLock，Esc，Spacebar，PageUp，PageDown，End，Home，Left，Right，Up，Down，PrintScreen，Insert，Del，Win，F1～F12，NumLock，Scroll 等。
+
+如果同时按下一个控制键和一个符号键，则返回符号键的键名。比如，按下 Ctrl + a，则返回`a`；按下 Shift + a，则返回大写的`A`。
+
+如果无法识别键名，返回字符串`Unidentified`。
+
+### KeyboardEvent.location
+
+`KeyboardEvent.location`属性返回一个整数，表示按下的键处在键盘的哪一个区域。它可能取以下值。
+
+- 0：处在键盘的主区域，或者无法判断处于哪一个区域。
+- 1：处在键盘的左侧，只适用那些有两个位置的键（比如 Ctrl 和 Shift 键）。
+- 2：处在键盘的右侧，只适用那些有两个位置的键（比如 Ctrl 和 Shift 键）。
+- 3：处在数字小键盘。
+
+### KeyboardEvent.repeat
+
+`KeyboardEvent.repeat`返回一个布尔值，代表该键是否被按着不放，以便判断是否重复这个键，即浏览器会持续触发`keydown`和`keypress`事件，直到用户松开手为止。
+
+## KeyboardEvent 的实例方法
+
+### KeyboardEvent.getModifierState()
+
+`KeyboardEvent.getModifierState()`方法返回一个布尔值，表示是否按下或激活指定的功能键。它的常用参数如下。
+
+- `Alt`：Alt 键
+- `CapsLock`：大写锁定键
+- `Control`：Ctrl 键
+- `Meta`：Meta 键
+- `NumLock`：数字键盘开关键
+- `Shift`：Shift 键
+
+```javascript
+if (
+  event.getModifierState('Control') +
+  event.getModifierState('Alt') +
+  event.getModifierState('Meta') > 1
+) {
+  return;
+}
+```
+
+上面代码表示，只要`Control`、`Alt`、`Meta`里面，同时按下任意两个或两个以上的键就返回。
+
