# [key]() Key管理设备按键事件 ### 方法: - [addEventListener](http://www.dcloud.io/docs/api/zh_cn/key.shtml#plus.key.addEventListener): 添加按键事件监听器 - [removeEventListener](http://www.dcloud.io/docs/api/zh_cn/key.shtml#plus.key.removeEventListener): 移除按键事件监听器 ### 对象: - [KeyType](http://www.dcloud.io/docs/api/zh_cn/key.shtml#plus.key.KeyType): 按键类型 - [KeyEvent](http://www.dcloud.io/docs/api/zh_cn/key.shtml#plus.key.KeyEvent): 按键事件 ### 回调方法: - [KeyEventCallback](http://www.dcloud.io/docs/api/zh_cn/key.shtml#plus.key.KeyEventCallback): 按键事件的回调函数 # [addEventListener]() 添加按键事件监听器 ~~~ plus.key.addEventListener( keyevent, listener, capture ); ~~~ ### 说明: 添加按键事件监听器,当指定的按键事件发生时,回调函数将触发。 应用中存在多个Webview窗口时,按照窗口的显示栈顺序从后往前查找,查找到添加按键事件监听器的窗口后停止(中断前面Webview窗口对按键事件的监听),并向窗口触发执行按键回调事件。 在同一Webview窗口中可多次调用此方法对同一事件添加多个监听器,触发时按照添加的顺序先后调用。 ### 参数: - event: *( [KeyType](http://www.dcloud.io/docs/api/zh_cn/key.shtml#plus.key.KeyType) ) 必选 *要监听的按键事件类型 - listener: *( [KeyEventCallback](http://www.dcloud.io/docs/api/zh_cn/key.shtml#plus.key.KeyEventCallback) ) 必选 *监听按键事件发生时调用的回调函数 - capture: *( Boolean ) 可选 *捕获按键事件流顺序,暂作为保留参数 ### 返回值: void : 无 ### 示例: ~~~ <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Key Example</title> <script type="text/javascript"> // 监听“返回”按钮事件 function addEventTest() { plus.key.addEventListener("backbutton",function(){ alert( "BackButton Key pressed!" ); }); } </script> </head> <body> <button onclick="addEventTest()">监听“返回”按键</button> </body> </html> ~~~ # [removeEventListener]() 移除按键事件监听器 ~~~ plus.key.removeEventListener( event, listener ); ~~~ ### 说明: 从窗口移除指定的事件监听器。若没有查找到对应的事件监听器,则无任何作用。 ### 参数: - event: *( [KeyType](http://www.dcloud.io/docs/api/zh_cn/key.shtml#plus.key.KeyType) ) 必选 *要移除的事件类型 - listener: *( [EventCallback](http://www.dcloud.io/docs/api/zh_cn/key.shtml#plus.key.EventCallback) ) 必选 *要移除回调函数对象 ### 返回值: void : 无 ### 示例: ~~~ <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Key Example</title> <script type="text/javascript"> function onback(){ alert( "BackButton Key pressed!" ); } // 监听“返回”按钮事件 function addEventTest() { plus.key.addEventListener("backbutton",onback); } // 取消监听“返回”按钮事件 function removeEventTest(){ plus.key.removeEventListener("backbutton",onback); } </script> </head> <body> <button onclick="addEventTest()">监听“返回”按键</button> <button onclick="removeEventTest()">取消监听“返回”按键</button> </body> </html> ~~~ # [KeyType]() 按键类型 ### 常量: - "backbutton": *(DOMString 类型)*设备“返回”按钮按键事件 如果需要改变默认“返回”按钮的处理逻辑,则可通过plus.key.addEventListener来注册监听"backbutton"事件。 ### 平台支持 - Android - 2.2+ (支持): 默认处理逻辑为退出应用。 - "keydown": *(DOMString 类型)*键按下事件 如果需要改变默认键按下的处理逻辑,则可通过plus.key.addEventListener来注册监听"keydown"事件。 可通过回调函数中KeyEvent对象的keyCode来获取按下的键值。 ### 平台支持 - Android - 2.2+ (支持): 默认处理逻辑由系统决定。 - "keyup": *(DOMString 类型)*键松开事件 如果需要改变默认键松开的处理逻辑,则可通过plus.key.addEventListener来注册监听"keyup"事件。 可通过回调函数中KeyEvent对象的keyCode来获取松开的键值。 ### 平台支持 - Android - 2.2+ (支持): 默认处理逻辑由系统决定。 - "longpressed": *(DOMString 类型)*长按键事件 如果需要改变默认长按键的处理逻辑,则可通过plus.key.addEventListener来注册监听"longpressed"事件。 长按键时会多次触发回调函数,通过回调函数中KeyEvent对象的keyCode来获取长按的键值。 ### 平台支持 - Android - 2.2+ (支持): 默认处理逻辑由系统决定。 - "menubutton": *(DOMString 类型)*设备“菜单”按钮按键事件 如果需要改变默认“菜单”按钮的处理逻辑,则可通过plus.key.addEventListener来注册监听"menubutton"事件。 ### 平台支持 - Android - 2.2+ (支持): 默认处理逻辑无操作。 - "searchbutton": *(DOMString 类型)*设备“搜索”按钮按键事件 如果需要改变默认“搜索”按钮的处理逻辑,则可通过plus.key.addEventListener来注册监听"searchbutton"事件。 ### 平台支持 - Android - 2.2+ (支持): 默认处理逻辑为打开系统搜索应用。 - "volumeupbutton": *(DOMString 类型)*设备“音量+”按钮按键事件 如果需要改变默认“音量+”按钮的处理逻辑,则可通过plus.key.addEventListener来注册监听"volumeupbutton"事件。 ### 平台支持 - Android - 2.2+ (支持): 默认处理逻辑为增加系统音量。 - "volumedownbutton": *(DOMString 类型)*设备“音量-”按钮按键事件 如果需要改变默认“音量-”按钮的处理逻辑,则可通过plus.key.addEventListener来注册监听"volumedownbutton"事件。 ### 平台支持 - Android - 2.2+ (支持): 默认处理逻辑为减少系统音量。 # [KeyEvent]() 按键事件 ### 属性: - [keyCode](http://www.dcloud.io/docs/api/zh_cn/key.shtml#plus.key.KeyEvent.keyCode): 触发按键事件的键值 - [keyType](http://www.dcloud.io/docs/api/zh_cn/key.shtml#plus.key.KeyEvent.keyType): 按键事件类型 # [keyCode]() 触发按键事件的键值 ### 说明: Number 类型 键值由各系统平台定义,一些特殊按键在不同的设备上可能存在差异。 ### 示例: ~~~ <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Key Example</title> <script type="text/javascript"> // H5 plus事件处理 function plusReady(){ // 监听键按下事件 plus.key.addEventListener("keydown",function(e){ console.log("keydown: "+e.keyCode); },false); // 监听键松开事件 plus.key.addEventListener("keyup",function(e){ console.log("keyup: "+e.keyCode); },false); // 监听长按键事件 plus.key.addEventListener("longpressed",function(e){ console.log("longpressed: "+e.keyCode); },false); } if(window.plus){ plusReady(); }else{ document.addEventListener("plusready",plusReady,false); } </script> </head> <body> 监听键事件<br/> </body> </html> ~~~ # [keyType]() 按键事件类型 ### 说明: KeyType 类型 用于表明触发此按键事件的类型,值为KeyType中定义的值。 # [KeyEventCallback]() 按键事件的回调函数 ~~~ void onKeyEvent( KeyEvent event ){ // Event handled code. var key=event.keyCode; // 用户按键的键值 } ~~~ ### 参数: - event: *( KeyEvent ) 必选 *监听用户按键操作返回的数据 可通过event的keyCode属性(String类型)获取用户按键的类型,参考KeyType类型。 ### 返回值: void : 无