跳到主要内容
版本：v5

@capacitor/keyboard

Keyboard API 提供键盘显示和可见性控制，以及键盘显示和隐藏时的事件跟踪。

安装​

npm install @capacitor/keyboard@latest-5
npx cap sync

示例​

import { Keyboard } from '@capacitor/keyboard';

Keyboard.addListener('keyboardWillShow', info => {
  console.log('键盘将显示，高度:', info.keyboardHeight);
});

Keyboard.addListener('keyboardDidShow', info => {
  console.log('键盘已显示，高度:', info.keyboardHeight);
});

Keyboard.addListener('keyboardWillHide', () => {
  console.log('键盘将隐藏');
});

Keyboard.addListener('keyboardDidHide', () => {
  console.log('键盘已隐藏');
});

配置​

在 iOS 上，可以通过以下选项配置键盘：

属性类型描述默认值自从
resize
KeyboardResize
配置键盘出现时应用程序的调整方式。仅在 iOS 上可用。native1.0.0
style
KeyboardStyle
如果你的应用不支持深色/浅色主题切换，则覆盖键盘样式。如果未设置，键盘样式将取决于设备外观。仅在 iOS 上可用。1.0.0
resizeOnFullScreenboolean有一个 Android 错误，阻止键盘在应用全屏时调整 WebView 大小（例如，如果使用 StatusBar 插件来重叠状态栏）。如果设置为 true，此设置会添加一个解决方案，使 WebView 即使在应用全屏时也能调整大小。仅 Android 可用。1.1.0

示例​

在 capacitor.config.json 中：

{
  "plugins": {
    "Keyboard": {
      "resize": "body",
      "style": "DARK",
      "resizeOnFullScreen": true
    }
  }
}

在 capacitor.config.ts 中：

/// <reference types="@capacitor/keyboard" />

import { CapacitorConfig } from '@capacitor/cli';
import { KeyboardResize, KeyboardStyle } from '@capacitor/keyboard';

const config: CapacitorConfig = {
  plugins: {
    Keyboard: {
      resize: KeyboardResize.Body,
      style: KeyboardStyle.Dark,
      resizeOnFullScreen: true,
    },
  },
};

export default config;

与 cordova-plugin-ionic-keyboard 的兼容性​

为了保持与 cordova-plugin-ionic-keyboard 的兼容性， 以下事件也可以通过 window.addEventListener 使用：

  • keyboardWillShow
  • keyboardDidShow
  • keyboardWillHide
  • keyboardDidHide

API​

show()​

show() => Promise<void>

显示键盘。此方法是 alpha 版本，可能存在一些问题。

此方法仅在 Android 上受支持。

自从: 1.0.0

hide()​

hide() => Promise<void>

隐藏键盘。

自从: 1.0.0

setAccessoryBarVisible(...)​

setAccessoryBarVisible(options: { isVisible: boolean; }) => Promise<void>

设置键盘上的辅助工具栏是否可见。我们建议在短表单（登录、注册等）上禁用 辅助工具栏，以提供更简洁的用户界面。

此方法仅在 iPhone 设备上受支持。

参数类型
options{ isVisible: boolean; }

自从: 1.0.0

setScroll(...)​

setScroll(options: { isDisabled: boolean; }) => Promise<void>

以编程方式启用或禁用 WebView 滚动。

此方法仅在 iOS 上受支持。

参数类型
options{ isDisabled: boolean; }

自从: 1.0.0

setStyle(...)​

setStyle(options: KeyboardStyleOptions) => Promise<void>

以编程方式设置键盘样式。

此方法仅在 iOS 上受支持。

参数类型
options
KeyboardStyleOptions

自从: 1.0.0

setResizeMode(...)​

setResizeMode(options: KeyboardResizeOptions) => Promise<void>

以编程方式设置调整大小模式。

此方法仅在 iOS 上受支持。

参数类型
options
KeyboardResizeOptions

自从: 1.0.0

getResizeMode()​

getResizeMode() => Promise<KeyboardResizeOptions>

获取当前设置的调整大小模式。

此方法仅在 iOS 上受支持。

返回: 

Promise<KeyboardResizeOptions>

自从: 4.0.0

addListener('keyboardWillShow', ...)​

addListener(eventName: 'keyboardWillShow', listenerFunc: (info: KeyboardInfo) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

监听键盘即将显示的事件。

在 Android 上，keyboardWillShow 和 keyboardDidShow 几乎同时触发。

参数类型
eventName'keyboardWillShow'
listenerFunc
(info: KeyboardInfo) => void

返回: 

Promise<PluginListenerHandle> & PluginListenerHandle

自从: 1.0.0

addListener('keyboardDidShow', ...)​

addListener(eventName: 'keyboardDidShow', listenerFunc: (info: KeyboardInfo) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

监听键盘已显示的事件。

在 Android 上，keyboardWillShow 和 keyboardDidShow 几乎同时触发。

参数类型
eventName'keyboardDidShow'
listenerFunc
(info: KeyboardInfo) => void

返回: 

Promise<PluginListenerHandle> & PluginListenerHandle

自从: 1.0.0

addListener('keyboardWillHide', ...)​

addListener(eventName: 'keyboardWillHide', listenerFunc: () => void) => Promise<PluginListenerHandle> & PluginListenerHandle

监听键盘即将隐藏的事件。

在 Android 上，keyboardWillHide 和 keyboardDidHide 几乎同时触发。

参数类型
eventName'keyboardWillHide'
listenerFunc() => void

返回: 

Promise<PluginListenerHandle> & PluginListenerHandle

自从: 1.0.0

addListener('keyboardDidHide', ...)​

addListener(eventName: 'keyboardDidHide', listenerFunc: () => void) => Promise<PluginListenerHandle> & PluginListenerHandle

监听键盘已隐藏的事件。

在 Android 上，keyboardWillHide 和 keyboardDidHide 几乎同时触发。

参数类型
eventName'keyboardDidHide'
listenerFunc() => void

返回: 

Promise<PluginListenerHandle> & PluginListenerHandle

自从: 1.0.0

removeAllListeners()​

removeAllListeners() => Promise<void>

移除此插件的所有原生监听器。

自从: 1.0.0

接口​

KeyboardStyleOptions​

属性类型描述默认值自从
style
KeyboardStyle
键盘样式。KeyboardStyle.Default1.0.0

KeyboardResizeOptions​

属性类型描述自从
mode
KeyboardResize
键盘出现时用于调整元素大小的模式。1.0.0

PluginListenerHandle​

属性类型
remove() => Promise<void>

KeyboardInfo​

属性类型描述自从
keyboardHeightnumber键盘的高度。1.0.0

枚举​

KeyboardStyle​

成员值描述自从
Dark'DARK'深色键盘。1.0.0
Light'LIGHT'浅色键盘。1.0.0
Default'DEFAULT'在 iOS 13 及更新版本上，键盘样式基于设备外观。如果设备使用深色模式，键盘将为深色。如果设备使用浅色模式，键盘将为浅色。在 iOS 12 上，键盘将为浅色。1.0.0

KeyboardResize​

成员值描述自从
Body'body'只有 body HTML 元素会被调整大小。相对单位不受影响，因为视口不会改变。1.0.0
Ionic'ionic'只有 ion-app HTML 元素会被调整大小。仅用于 Ionic Framework 应用。1.0.0
Native'native'整个原生 Web View 会在键盘显示/隐藏时调整大小。这会影响 vh 相对单位。1.0.0
None'none'应用和 Web View 都不会被调整大小。1.0.0

Contents

编辑此页