Back to Uni App

Keyboard

docs/api/keyboard.md

2.3.310.2 KB
Original Source
<!-- ## uni.hideKeyboard(options) @hidekeyboard -->

::: sourceCode

uni.hideKeyboard(options?) @hidekeyboard

GitCode: https://gitcode.com/dcloud/uni-api/tree/alpha/uni_modules/uni-keyboard

GitHub: https://github.com/dcloudio/uni-api/tree/alpha/uni_modules/uni-keyboard

:::

隐藏键盘

hideKeyboard 兼容性

Web微信小程序AndroidiOSHarmonyOSHarmonyOS(Vapor)
4.04.414.714.714.615.0

参数

名称类型必填默认值兼容性描述
optionsHideKeyboardOptions-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -uni.hideKeyboard参数定义

options 的属性描述

名称类型必备默认值兼容性描述
success(res: HideKeyboardSuccess) => void-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -uni.hideKeyboard成功回调函数定义
fail(res: HideKeyboardFail) => void-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -uni.hideKeyboard失败回调函数定义
complete(res: any) => void-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -uni.hideKeyboard完成回调函数定义
<!-- UTSAPIJSON.hideKeyboard.example -->

参见

<!-- ## uni.onKeyboardHeightChange(callback) @onkeyboardheightchange -->

::: sourceCode

uni.onKeyboardHeightChange(callback) @onkeyboardheightchange

GitCode: https://gitcode.com/dcloud/uni-api/tree/alpha/uni_modules/uni-keyboard

GitHub: https://github.com/dcloudio/uni-api/tree/alpha/uni_modules/uni-keyboard

:::

监听键盘高度变化事件

在input和textarea组件上也有事件用于监听键盘高度变化。本API为全局API,可以全局监听键盘弹出收起和高度变化,尤其是App内嵌web-view中的键盘变化,无法在组件上监听,只能使用本API全局监听。

onKeyboardHeightChange 兼容性

Web微信小程序AndroidiOSHarmonyOS
-4.414.714.71-

参数

名称类型必填默认值兼容性描述
callback(res: OnKeyboardHeightChangeCallbackResult) => void-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -uni.onKeyboardHeightChange参数定义

OnKeyboardHeightChangeCallbackResult 的属性值 @onkeyboardheightchangecallbackresult-values

名称类型必备默认值兼容性描述
heightnumber-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -键盘高度

返回值

类型
number
<!-- UTSAPIJSON.onKeyboardHeightChange.example -->

参见

<!-- ## uni.offKeyboardHeightChange(id) @offkeyboardheightchange -->

::: sourceCode

uni.offKeyboardHeightChange(id?) @offkeyboardheightchange

GitCode: https://gitcode.com/dcloud/uni-api/tree/alpha/uni_modules/uni-keyboard

GitHub: https://github.com/dcloudio/uni-api/tree/alpha/uni_modules/uni-keyboard

:::

移除键盘高度变化事件的监听函数

offKeyboardHeightChange 兼容性

Web微信小程序AndroidiOSHarmonyOS
-4.414.714.71-

参数

名称类型必填默认值兼容性描述
idnumber--
<!-- UTSAPIJSON.offKeyboardHeightChange.example -->

参见

示例

示例为hello uni-app x alpha分支,与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见 ::: preview https://hellouniappx.dcloud.net.cn/web/#/pages/API/keyboard/keyboard

appRedirect https://hellouniappx.dcloud.net.cn/appredirect.html?path=pages/API/keyboard/keyboard

示例

vue
<template>
	<view class="container">
		<view class="input-section">
			<input id="uni-input-box" class="input-box" type="text" :value="data.inputValue" placeholder="点击输入框显示键盘" :focus="data.isFocus" hold-keyboard="true" />
			<button class="btn" @click="hideKeyboard">隐藏键盘</button>
		</view>
		<view class="info-section">
			<text class="info-text">键盘高度: {{data.keyboardHeight}}px</text>
			<text class="info-text">键盘状态: {{data.keyboardStatus}}</text>
		</view>
	</view>
</template>

<script setup lang="uts">

type DataType = {
  inputValue: string,
  isFocus: boolean,
  keyboardHeight: number,
  keyboardStatus: string,
}

// 使用reactive包装数据,便于自动化测试获取
const data = reactive({
  inputValue: '',
  isFocus: false,
  keyboardHeight: 0,
  keyboardStatus: '未显示',
} as DataType)

function hideKeyboard() {
  uni.hideKeyboard();
}

onLoad(() => {
  // 监听键盘高度变化
  uni.onKeyboardHeightChange(res => {
    data.keyboardHeight = res.height;
    data.keyboardStatus = res.height > 0 ? '显示中' : '已隐藏';
  });
})

onUnload(() => {
  // 页面卸载时移除监听
  uni.offKeyboardHeightChange();
})

defineExpose({
  data,
  hideKeyboard
})
</script>

<style>
.container {
	padding: 20px;
}
.input-section {
	margin-bottom: 20px;
}
.input-box {
	width: 100%;
	height: 40px;
	border: 1px solid #ccc;
	border-radius: 4px;
	padding: 0 10px;
	margin-bottom: 10px;
}
.btn {
	background-color: #007AFF;
	color: #fff;
}
.info-section {
	margin-top: 20px;
}
.info-text {
	width: 100%;
	margin-bottom: 10px;
	font-size: 16px;
	color: #333;
}
</style>

:::

通用类型

GeneralCallbackResult

名称类型必备默认值兼容性描述
errMsgstring-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -错误信息