docs/api/keyboard.md
::: sourceCode
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
:::
隐藏键盘
| Web | 微信小程序 | Android | iOS | HarmonyOS | HarmonyOS(Vapor) |
|---|---|---|---|---|---|
| 4.0 | 4.41 | 4.71 | 4.71 | 4.61 | 5.0 |
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| options | HideKeyboardOptions | 否 | - | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | uni.hideKeyboard参数定义 |
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| 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完成回调函数定义 |
::: sourceCode
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全局监听。
| Web | 微信小程序 | Android | iOS | HarmonyOS |
|---|---|---|---|---|
| - | 4.41 | 4.71 | 4.71 | - |
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| callback | (res: OnKeyboardHeightChangeCallbackResult) => void | 是 | - | Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: - | uni.onKeyboardHeightChange参数定义 |
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| height | number | 是 | - | Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: - | 键盘高度 |
| 类型 |
|---|
| number |
::: sourceCode
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
:::
移除键盘高度变化事件的监听函数
| Web | 微信小程序 | Android | iOS | HarmonyOS |
|---|---|---|---|---|
| - | 4.41 | 4.71 | 4.71 | - |
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| id | number | 否 | - | - |
示例为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
示例
<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>
:::
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| errMsg | string | 是 | - | Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: - | 错误信息 |