initial commit

1 files changed, 292 insertions, 0 deletions

diff --git a/files/zh-cn/web/api/keyboardevent/key/index.html b/files/zh-cn/web/api/keyboardevent/key/index.html
new file mode 100644
index 0000000000..617cc4f7b9
--- /dev/null
+++ b/files/zh-cn/web/api/keyboardevent/key/index.html
@@ -0,0 +1,292 @@
+---
+title: KeyboardEvent.key
+slug: Web/API/KeyboardEvent/key
+tags:
+  - 参考
+  - 只读属性
+  - 属性
+  - 键盘事件
+translation_of: Web/API/KeyboardEvent/key
+---
+<p>{{APIRef("DOM Events")}}</p>
+
+<p><span class="seoSummary">只读属性 <strong><code>KeyboardEvent.key</code></strong> 返回用户按下的物理按键的值。它还与 <code>shiftKey</code> 等调节性按键的状态和键盘的区域 / 和布局有关。</span>它的值由以下因素决定：</p>
+
+<div class="pull-aside">
+<p class="moreinfo">查看 <a href="/docs/Web/API/KeyboardEvent/key/Key_Values">所有键值列表</a></p>
+</div>
+
+<ul>
+ <li>如果按下的键拥有可打印的内容，则返回一个非空的 Unicode 字符来代表这个键的可打印内容。</li>
+ <li>如果按下的键是一个控制键或特殊字符，则返回一个事先定义好的值，见<a href="/zh-CN/docs/Web/API/KeyboardEvent/key/Key_Values">预定义键值列表</a>。</li>
+ <li>如果 <code>KeyboardEvent</code> 显示按下的键是一个死键（dead key），则键值为 <code>"Dead"</code>。</li>
+ <li>有些特殊键盘的键（比如多媒体键盘上用来控制媒体播放的扩展按键）在 Windows 下会触发 <code>WM_APPCOMMAND</code> 事件，而不会产生按键代码。虽然没有按键代码，这些事件将映射到 DOM 键盘事件中，并将列入 Windows 的“虚拟按键码”列表中。</li>
+ <li>如果按键无法识别，则返回 <code>"Unidentified"</code>。</li>
+</ul>
+
+<h2 id="KeyboardEvent_次序">KeyboardEvent 次序</h2>
+
+<p><code>KeyboardEvent</code> 事件以一个预设的次序触发，理解这一点对于理解特定 <code>KeyboardEvent</code> 的 <code>key</code> 属性值大有帮助。对于一个给定的按键操作，<code>KeyboardEvent</code> 将假定 {{domxref("Event.preventDefault")}} 未调用并按下面次序触发：</p>
+
+<ol>
+ <li>首先触发 {{event("keydown")}} 事件。如果按键长按且生成一个字符，则事件将以一个与平台实现方式相关的时间间隔持续发出，同时将只读属性 {{domxref("KeyboardEvent.repeat")}} 设定为 <code>true</code>。</li>
+ <li>如果按键生成的字符即将插入某个 {{HTMLElement("input")}}、{{HTMLElement("textarea")}} 或其它某个 {{domxref("HTMLElement.contentEditable")}} 设为 true 的元素，则依次触发 {{event("beforeinput")}}、{{event("input")}}事件。注意某些实现中若支持 {{event("keypress")}} 事件则可能将其触发。当按键长按时重复触发。</li>
+ <li>当按键松开时触发 {{event("keyup")}} 事件。操作结束。</li>
+</ol>
+
+<p>在次序1、3中，<code>KeyboardEvent.key</code> 属性按照事先定义的规则设定为恰当的值。</p>
+
+<h2 id="KeyboardEvent_次序示例">KeyboardEvent 次序示例</h2>
+
+<p>考虑使用美国或英国键盘布局生成的点击 <code>shiftKey</code> 和一个未知的 <code>key 2</code> 时的事件次序。</p>
+
+<p>请检测以下两个测试用例：</p>
+
+<ol>
+ <li>按下并长按 <code>shift</code> 键，然后按下 <code>key 2</code> 并松开。下一步，松开 <code>shift</code> 键。</li>
+ <li>按下并长按 <code>shift</code> 键，然后按下并长按 <code>key 2</code>。然后松开 shift 键，最后松开 <code>key 2</code>。</li>
+</ol>
+
+<h3 id="HTML">HTML</h3>
+
+<pre class="brush: html">&lt;div class="flex flex-left"&gt;
+    &lt;textarea rows="5" id="test-target"&gt;&lt;/textarea&gt;
+    &lt;button id="btn-clear-console"&gt;清空控制台&lt;/button&gt;
+&lt;/div&gt;
+&lt;div class="flex flex-right"&gt;
+    &lt;div id="console-log"&gt;&lt;/div&gt;
+&lt;/div&gt;
+&lt;script src="main.js"&gt;&lt;/script&gt;</pre>
+
+<h3 id="CSS">CSS</h3>
+
+<pre class="brush: css">body {
+    -webkit-display: flex;
+    display: flex;
+}
+
+.flex {
+    padding-left: 20px;
+    padding-right: 20px;
+}
+
+.flex-left {
+    flex: 1;
+    flex-grow: 1;
+    -webkit-flex: 1;
+    -webkit-flex-grow: 1;
+}
+
+.flex-right {
+    flex: 2;
+    flex-grow: 2;
+    -webkit-flex: 2;
+    -webkit-flex-grow: 2;
+}
+
+#test-target {
+    display: block;
+    width: 100%;
+    margin-bottom: 10px;
+    resize: none;
+}
+
+#console-log {
+    overflow: auto;
+}</pre>
+
+<h3 id="JavaScript">JavaScript</h3>
+
+<pre class="brush: js">let textarea = document.getElementById('test-target'),
+consoleLog = document.getElementById('console-log'),
+btnClearConsole = document.getElementById('btn-clear-console');
+
+function logMessage(message) {
+  let p = document.createElement('p');
+  p.appendChild(document.createTextNode(message));
+  consoleLog.appendChild(p);
+}
+
+textarea.addEventListener('keydown', (e) =&gt; {
+  if (!e.repeat)
+    logMessage(`第一个 keydown 事件。key 属性的值为"${e.key}"`);
+  else
+    logMessage(`keydown 事件重复。key 属性的值为"${e.key}"`);
+});
+
+textarea.addEventListener('beforeinput', (e) =&gt; {
+  logMessage(`beforeinput 事件。你准备输入"${e.data}"`);
+});
+
+textarea.addEventListener('input', (e) =&gt; {
+  logMessage(`input 事件。你刚刚输入了"${e.data}"`);
+});
+
+textarea.addEventListener('keyup', (e) =&gt; {
+  logMessage(`keyup 事件。key 属性的值为"${e.key}"`);
+});
+
+btnClearConsole.addEventListener('click', (e) =&gt; {
+  let child = consoleLog.firstChild;
+  while (child) {
+   consoleLog.removeChild(child);
+   child = consoleLog.firstChild;
+  }
+});</pre>
+
+<h3 id="运行结果">运行结果</h3>
+
+<div class="hidden">
+<h6 id="Key">Key</h6>
+
+<pre class="brush: html">&lt;!DOCTYPE html&gt;
+&lt;html lang="zh-CN"&gt;
+&lt;head&gt;
+    &lt;meta charset="UTF-8"&gt;
+    &lt;style&gt;
+    body { -webkit-display: flex; display: flex; }
+    .flex { padding-left: 20px; padding-right: 20px; }
+    .flex-left { flex: 1; flex-grow: 1; -webkit-flex: 1; -webkit-flex-grow: 1; }
+    .flex-right { flex: 2; flex-grow: 2; -webkit-flex: 2; -webkit-flex-grow: 2; }
+    #test-target { display: block; width: 100%; margin-bottom: 10px; resize: none; }
+    #console-log { overflow: auto; }
+    &lt;/style&gt;
+    &lt;title&gt;KeyboardEvent.key&lt;/title&gt;
+&lt;/head&gt;
+
+&lt;body&gt;
+    &lt;div class="flex flex-left"&gt;
+        &lt;textarea rows="5" id="test-target"&gt;&lt;/textarea&gt;
+        &lt;button id="btn-clear-console"&gt;清空控制台&lt;/button&gt;
+    &lt;/div&gt;
+    &lt;div class="flex flex-right"&gt;
+        &lt;div id="console-log"&gt;&lt;/div&gt;
+    &lt;/div&gt;
+    &lt;script&gt;
+    let textarea = document.getElementById('test-target'),
+    consoleLog = document.getElementById('console-log'),
+    btnClearConsole = document.getElementById('btn-clear-console');
+
+    function logMessage(message) {
+        let p = document.createElement('p');
+        p.appendChild(document.createTextNode(message));
+        consoleLog.appendChild(p);
+    }
+
+    textarea.addEventListener('keydown', (e) =&gt; {
+        if (!e.repeat)
+            logMessage(`第一个 keydown 事件。key 属性的值为"${e.key}"`);
+        else
+            logMessage(`keydown 事件重复。key 属性的值为"${e.key}"`);
+    });
+
+    textarea.addEventListener('beforeinput', (e) =&gt; {
+        logMessage(`beforeinput 事件。你准备输入"${e.data}"`);
+    });
+
+    textarea.addEventListener('input', (e) =&gt; {
+        logMessage(`input 事件。你刚刚输入了"${e.data}"`);
+    });
+
+    textarea.addEventListener('keyup', (e) =&gt; {
+        logMessage(`keyup 事件。key 属性的值为"${e.key}"`);
+    });
+
+
+    btnClearConsole.addEventListener('click', (e) =&gt; {
+        let child = consoleLog.firstChild;
+        while (child) {
+            consoleLog.removeChild(child);
+            child = consoleLog.firstChild;
+        }
+    });
+    &lt;/script&gt;
+&lt;/body&gt;
+&lt;/html&gt;</pre>
+</div>
+
+<p>{{ EmbedLiveSample('Key', '100%', 480, "", "", "hide-codepen-jsfiddle") }}</p>
+
+<h3 id="用例_1">用例 1</h3>
+
+<p>当按下 shift 键时，首先触发 {{event("keydown")}} 事件，然后将 <code>key</code> 属性的值设为 <code>"Shift"</code> 字符串。如果继续长按 shift 键，由于不会生成字符按键值，{{event("keydown")}} 事件不会继续重复触发。</p>
+
+<p>当按下 <code>key 2</code> 时，另一个 {{event("keydown")}} 事件将会为这个新的按键动作触发，若使用的是美式键盘，它的 <code>key</code> 属性将被设为 <code>"@"</code> 字符，若为英式键盘，则会设为 <code>"""</code> 字符。这是因为 <code>key</code> 属性 <code>"shift"</code> 处于激活状态。由于生成了一个字符的按键值，{{event("beforeinput")}} 和 {{event("input")}} 事件随后触发。</p>
+
+<p>松开 <code>key 2</code> 时，{{event("keyup")}} 事件将触发，<code>key</code> 属性将会为不同键盘布局设定合适的字符值，比如 <code>"@"</code>、<code>"""</code>。</p>
+
+<p>最后在松开 shift 键时，另一个 {{event("keyup")}} 事件触发，<code>key</code> 值将保持 <code>"Shift"</code> 不变。</p>
+
+<h3 id="用例_2">用例 2</h3>
+
+<p>当按下 shift 键时，首先触发 {{event("keydown")}} 事件，然后将 <code>key</code> 属性的值设为 <code>"Shift"</code> 字符串。如果继续长按 shift 键，由于不会生成字符按键值，{{event("keydown")}} 事件不会继续重复触发。</p>
+
+<p>当按下 <code>key 2</code> 时，另一个 {{event("keydown")}} 事件将会为这个新的按键动作触发，若使用的是美式键盘，它的 <code>key</code> 属性将被设为 <code>"@"</code> 字符，若为英式键盘，则会设为 <code>"""</code> 字符。这是因上档键处于激活状态。由于生成了一个字符的按键值，{{event("beforeinput")}} 和 {{event("input")}} 事件随后触发。如果继续长按 <code>2</code> 键，则 {{event("keydown")}} 事件将持续重复触发，同时将 {{domxref("KeyboardEvent.repeat")}} 属性设置为 <code>true</code>。{{event("beforeinput")}} 和 {{event("input")}} 事件也将持续重复触发。</p>
+
+<p>当松开 shift 键时，{{event("keyup")}} 事件随之触发，且 <code>key</code> 属性保留为 <code>"Shift"</code>。此时请注意为  <code>key 2</code> 长按触发的重复 <code>keydown</code> 事件的 <code>key</code> 值会变成 <code>"2"</code>，因为上档键不再处于激活状态。{{event("beforeinput")}} 与 {{event("input")}} 事件的 {{domxref("InputEvent.data")}} 属性同理。</p>
+
+<p>最终 <code>key 2</code> 松开，{{event("keyup")}} 事件触发，但两种键盘布局的 <code>key</code> 属性均为 <code>"2"</code>。就是因为没有激活上档键。</p>
+
+
+
+<h2 id="示例"><font face="x-locale-heading-primary, zillaslab, Palatino, Palatino Linotype, x-locale-heading-secondary, serif"><span style="font-size: 37.33327865600586px;"><strong>示例</strong></span></font></h2>
+
+<p>这个示例使用 {{domxref("EventTarget.addEventListener()")}} 监听 {{event("keydown")}} 事件。当我们事件触发时，将检测按键的值是否为代码所关注，如果是，就进行某项操作。（可能是给飞船转向，或者是调整电子表格中选中单元格的位置。）</p>
+
+<pre class="brush: js">window.addEventListener("keydown", function (event) {
+  if (event.defaultPrevented) {
+    return; // 如果事件已经在进行中，则不做任何事。
+  }
+
+  switch (event.key) {
+    case "ArrowUp":
+      // 按“↑”方向键时要做的事。
+      break;
+    case "ArrowDown":
+      // 按“↓”方向键时要做的事。
+      break;
+    case "ArrowLeft":
+      // 按“←”方向键时要做的事。
+      break;
+    case "ArrowRight":
+      // 按“→”方向键时要做的事。
+      break;
+    case "Enter":
+      // 按“回车”键时要做的事。
+      break;
+    case "Escape":
+      // 按“ESC”键时要做的事。
+      break;
+    default:
+      return; // 什么都没按就退出吧。
+  }
+
+  // 取消默认动作，从而避免处理两次。
+  event.preventDefault();
+}, true);
+</pre>
+
+<p><font face="x-locale-heading-primary, zillaslab, Palatino, Palatino Linotype, x-locale-heading-secondary, serif"><span style="font-size: 37.33327865600586px;"><strong>标准</strong></span></font></p>
+
+
+
+<table class="standard-table">
+ <tbody>
+  <tr>
+   <th scope="col">标准</th>
+   <th scope="col">状态</th>
+   <th scope="col">备注</th>
+  </tr>
+  <tr>
+   <td>{{SpecName('DOM3 Events', '#widl-KeyboardEvent-key', 'KeyboardEvent.key')}}</td>
+   <td>{{Spec2('DOM3 Events')}}</td>
+   <td>初次定义，包括按键的值。</td>
+  </tr>
+ </tbody>
+</table>
+
+
+
+<h2 id="兼容性">兼容性</h2>
+
+<p>{{Compat("api.KeyboardEvent.key")}}</p>