@capacitor/keyboard

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

安装

npm install @capacitor/keyboard
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 上，可以使用以下选项配置键盘：

Prop	Type	Description	Default	Since
resize	KeyboardResize	配置键盘出现时调整应用程序大小的方式。仅适用于 iOS。	native	1.0.0
style	KeyboardStyle	如果您的应用程序不支持深色/浅色主题更改，则覆盖键盘样式。如果未设置，键盘样式将取决于设备外观。仅适用于 iOS。		1.0.0
resizeOnFullScreen	boolean	有一个 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()
• hide()
• setAccessoryBarVisible(...)
• setScroll(...)
• setStyle(...)
• setResizeMode(...)
• getResizeMode()
• addListener('keyboardWillShow', ...)
• addListener('keyboardDidShow', ...)
• addListener('keyboardWillHide', ...)
• addListener('keyboardDidHide', ...)
• removeAllListeners()
• Interfaces
• Enums

show()

show() => Promise<void>

显示键盘。

此方法仅在 Android 上受支持。

Since: 1.0.0

---

hide()

hide() => Promise<void>

隐藏键盘。

Since: 1.0.0

---

setAccessoryBarVisible(...)

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

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

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

Param	Type
options	{ isVisible: boolean; }

Since: 1.0.0

---

setScroll(...)

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

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

此方法仅在 iOS 上受支持。

Param	Type
options	{ isDisabled: boolean; }

Since: 1.0.0

---

setStyle(...)

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

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

此方法仅在 iOS 上受支持。

Param	Type
options	KeyboardStyleOptions

Since: 1.0.0

---

setResizeMode(...)

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

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

此方法仅在 iOS 上受支持。

Param	Type
options	KeyboardResizeOptions

Since: 1.0.0

---

getResizeMode()

getResizeMode() => Promise<KeyboardResizeOptions>

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

此方法仅在 iOS 上受支持。

Returns:

Promise<KeyboardResizeOptions>

Since: 4.0.0

---

addListener('keyboardWillShow', ...)

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

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

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

Param	Type
eventName	'keyboardWillShow'
listenerFunc	(info: KeyboardInfo) => void

Returns:

Promise<PluginListenerHandle>

Since: 1.0.0

---

addListener('keyboardDidShow', ...)

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

监听键盘已显示的事件。

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

Param	Type
eventName	'keyboardDidShow'
listenerFunc	(info: KeyboardInfo) => void

Returns:

Promise<PluginListenerHandle>

Since: 1.0.0

---

addListener('keyboardWillHide', ...)

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

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

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

Param	Type
eventName	'keyboardWillHide'
listenerFunc	() => void

Returns:

Promise<PluginListenerHandle>

Since: 1.0.0

---

addListener('keyboardDidHide', ...)

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

监听键盘已隐藏的事件。

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

Param	Type
eventName	'keyboardDidHide'
listenerFunc	() => void

Returns:

Promise<PluginListenerHandle>

Since: 1.0.0

---

removeAllListeners()

removeAllListeners() => Promise<void>

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

Since: 1.0.0

---

Interfaces

KeyboardStyleOptions

Prop	Type	Description	Default	Since
style	KeyboardStyle	键盘的样式。	KeyboardStyle.Default	1.0.0

KeyboardResizeOptions

Prop	Type	Description	Since
mode	KeyboardResize	键盘出现时用于调整元素大小的模式。	1.0.0

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

KeyboardInfo

Prop	Type	Description	Since
keyboardHeight	number	键盘的高度。	1.0.0

Enums

KeyboardStyle

Members	Value	Description	Since
Dark	'DARK'	深色键盘。	1.0.0
Light	'LIGHT'	浅色键盘。	1.0.0
Default	'DEFAULT'	键盘样式基于设备外观。如果设备使用深色模式，键盘将为深色。如果设备使用浅色模式，键盘将为浅色。	1.0.0

KeyboardResize

Members	Value	Description	Since
Body	'body'	只有 body HTML 元素将被调整大小。相对单位不受影响，因为视口不会改变。	1.0.0
Ionic	'ionic'	只有 ion-app HTML 元素将被调整大小。仅用于 Ionic Framework 应用程序。	1.0.0
Native	'native'	当键盘显示/隐藏时，整个原生 Web 视图将被调整大小。这会影响 vh 相对单位。	1.0.0
None	'none'	应用程序和 Web 视图都不会被调整大小。	1.0.0