key

Key管理设备按键事件

方法：

对象：

回调方法：

权限：

5+功能模块（permissions）

  2. {
  3. // ...
  4. "permissions":{
  5.     // ...
  6.     "Webview": {
  7.         "description": "窗口管理"
  8.     }
  9. }
  10. }
  11.

addEventListener

添加按键事件监听器

  2. plus.key.addEventListener( keyevent, listener, capture );
  3.

说明：

添加按键事件监听器，当指定的按键事件发生时，回调函数将触发。应用中存在多个Webview窗口时，按照窗口的显示栈顺序从后往前查找，查找到添加按键事件监听器的窗口后停止（中断前面Webview窗口对按键事件的监听），并向窗口触发执行按键回调事件。在同一Webview窗口中可多次调用此方法对同一事件添加多个监听器，触发时按照添加的顺序先后调用。注意：此方法无法监听软键盘的按键事件。

参数：

  • event: (KeyType)必选 要监听的按键事件类型
  • listener: (KeyEventCallback)必选 监听按键事件发生时调用的回调函数
  • capture: (Boolean)可选 捕获按键事件流顺序，暂作为保留参数

返回值：

void: 无

示例：

  2. <!DOCTYPE html>
  3. <html>
  4.     <head>
  5.     <meta charset="utf-8">
  6.     <title>Key Example</title>
  7.     <script type="text/javascript">
  8. // 监听“返回”按钮事件
  9. function addEventTest() {
  10.     plus.key.addEventListener("backbutton",function(){
  11.         alert( "BackButton Key pressed!" );
  12.     });
  13. }
  14.     </script>
  15.     </head>
  16.     <body>
  17.         <button onclick="addEventTest()">监听“返回”按键</button>
  18.     </body>
  19. </html>
  20.

uni-app使用plus注意事项

hideSoftKeybord

隐藏软键盘

  2. void plus.key.hideSoftKeybord();
  3.

说明：

隐藏已经显示的软键盘，如果软键盘没有显示则不做任何操作。

参数：

无

返回值：

void: 无

示例：

  2. <!DOCTYPE html>
  3. <html>
  4.     <head>
  5.     <meta charset="utf-8">
  6.     <title>Key Example</title>
  7.     <script type="text/javascript">
  8. // H5 plus事件处理
  9. function plusReady(){
  10. }
  11. if(window.plus){
  12.     plusReady();
  13. }else{
  14.     document.addEventListener('plusready', plusReady, false);
  15. }
  16.     </script>
  17.     </head>
  18.     <body>
  19.         编辑框：<input type="text" placeholder="请输入"></input><br/>
  20.         <button onclick="plus.key.hideSoftKeybord()">隐藏软键盘</button><br/>
  21.     </body>
  22. </html>
  23.

uni-app使用plus注意事项

setAssistantType

设置辅助输入类型


void plus.key.setAssistantType(type);

说明：

input的type类型为text获取焦点时，在软键盘上方显示辅助输入条方便用户快速输入。在页面中input编辑框type类型不为"tel"、"email"时生效（type为tel类型时一定显示tel的辅助输入条，type为email时一定显示email的辅助输入条）。

参数：

  • type: (String)必选 辅助输入类型可取值："nick" - 用户名（昵称）类型，自动保存最后输入的两个用户名，并在辅助输入条上显示； "address" - 地址类型，在辅助输入条上显示当前位置（定位获取）、家庭地址（在设置界面中配置）、单位地址（在设置界面中配置）； "tel" - 电话号码类型，自动保存最后两次输入的两个手机号码显示在辅助输入条上，与input的type类型为tel逻辑一致； "email" - 邮箱地址类型，自动保存最后两次输入的两个邮箱地址显示在辅助输入条上，与Input的type类型为email逻辑一致； "company" - 公司名称类型，自动保存最后一次输入的公司名称显示在辅助输入条上； "tax" - 税号类型，自动保存最后一次输入的企业税务标识显示在辅助输入条上； "id" - 身份证号码类型，自动保存最后一次输入的身份证号显示在辅助输入条上； "none" - 不使用辅助输入。

返回值：

void: 无

示例：


<!DOCTYPE html>
<html>
    <head>
    <meta charset="utf-8">
    <title>Key Example</title>
    <script type="text/javascript">
// H5 plus事件处理
function plusReady(){
}
if(window.plus){
    plusReady();
}else{
    document.addEventListener('plusready', plusReady, false);
}
    </script>
    </head>
    <body>
        用户名编辑框：<input type="text" onfocus="plus.key.setAssistantType('nick')" onblur="plus.key.setAssistantType('none')" placeholder="请输入用户名"></input><br/>
        地址编辑框：<input type="text" onfocus="plus.key.setAssistantType('address')" onblur="plus.key.setAssistantType('none')" placeholder="请输入地址"></input><br/>
    </body>
</html>

uni-app使用plus注意事项

showSoftKeybord

显示软键盘


void plus.key.showSoftKeybord();

说明：

强制显示系统软键盘，如果软键盘已经显示则不做任何操作。

参数：

无

返回值：

void: 无

平台支持：

  • Android- ALL(支持)
  • iOS- ALL(不支持): 需获取DOM中的input元素并调用其focus方法获取焦点才能主动弹出系统软键盘。

示例：


<!DOCTYPE html>
<html>
    <head>
    <meta charset="utf-8">
    <title>Key Example</title>
    <script type="text/javascript">
// H5 plus事件处理
function plusReady(){
}
if(window.plus){
    plusReady();
}else{
    document.addEventListener('plusready', plusReady, false);
}
    </script>
    </head>
    <body>
        编辑框：<input type="text" placeholder="请输入"></input><br/>
        <button onclick="plus.key.showSoftKeybord()">显示软键盘</button><br/>
    </body>
</html>

uni-app使用plus注意事项

removeEventListener

移除按键事件监听器


plus.key.removeEventListener( event, listener );

说明：

从窗口移除指定的事件监听器。若没有查找到对应的事件监听器，则无任何作用。

参数：

返回值：

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>

uni-app使用plus注意事项

KeyType

按键类型

常量：

  • "backbutton": (String类型)设备“返回”按钮按键事件如果需要改变默认“返回”按钮的处理逻辑，则可通过plus.key.addEventListener来注册监听"backbutton"事件。

平台支持

  • Android - 2.2+ (支持): 默认处理逻辑为退出应用。
  • iOS - ALL (支持): 标题栏的“返回”按钮点击时触发此事件。默认不处理此事件。
    • "keydown": (String类型)键按下事件如果需要改变默认键按下的处理逻辑，则可通过plus.key.addEventListener来注册监听"keydown"事件。可通过回调函数中KeyEvent对象的keyCode来获取按下的键值。

平台支持

  • Android - 2.2+ (支持): 根据系统keydown事件触发，软键盘不会触发此事件。默认处理逻辑由系统决定。
  • iOS - ALL (不支持): 不触发此事件。
    • "keyup": (String类型)键松开事件如果需要改变默认键松开的处理逻辑，则可通过plus.key.addEventListener来注册监听"keyup"事件。可通过回调函数中KeyEvent对象的keyCode来获取松开的键值。

平台支持

  • Android - 2.2+ (支持): 根据系统keyup事件触发，软键盘不会触发此事件。默认处理逻辑由系统决定。
  • iOS - ALL (不支持): 不触发此事件。
    • "longpressed": (String类型)长按键事件如果需要改变默认长按键的处理逻辑，则可通过plus.key.addEventListener来注册监听"longpressed"事件。长按键时会多次触发回调函数，通过回调函数中KeyEvent对象的keyCode来获取长按的键值。

平台支持

  • Android - 2.2+ (支持): 根据系统keyup事件触发，软键盘不会触发此事件。默认处理逻辑由系统决定。
  • iOS - ALL (不支持): 不触发此事件。
    • "menubutton": (String类型)设备“菜单”按钮按键事件如果需要改变默认“菜单”按钮的处理逻辑，则可通过plus.key.addEventListener来注册监听"menubutton"事件。

平台支持

  • Android - 2.2+ (支持): 默认处理逻辑无操作。
  • iOS - ALL (不支持): 不触发此事件。
    • "searchbutton": (String类型)设备“搜索”按钮按键事件如果需要改变默认“搜索”按钮的处理逻辑，则可通过plus.key.addEventListener来注册监听"searchbutton"事件。

平台支持

  • Android - 2.2+ (支持): 默认处理逻辑为打开系统搜索应用。
  • iOS - ALL (不支持): 不触发此事件。
    • "volumeupbutton": (String类型)设备“音量+”按钮按键事件如果需要改变默认“音量+”按钮的处理逻辑，则可通过plus.key.addEventListener来注册监听"volumeupbutton"事件。

平台支持

  • Android - 2.2+ (支持): 默认处理逻辑为增加系统音量。
  • iOS - ALL (不支持): 不触发此事件。
    • "volumedownbutton": (String类型)设备“音量-”按钮按键事件如果需要改变默认“音量-”按钮的处理逻辑，则可通过plus.key.addEventListener来注册监听"volumedownbutton"事件。

平台支持

  • Android - 2.2+ (支持): 默认处理逻辑为减少系统音量。
  • iOS - ALL (不支持): 不触发此事件。

KeyEvent

按键事件

属性：

  • 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: 无