键盘

定制和考虑屏幕键盘的存在是开发者在构建移动应用和 PWA 时面临的两个常见障碍。本指南将介绍可用于管理应用中的屏幕键盘的各种工具。

¥Customizing and accounting for the presence of an on-screen keyboard are two common roadblocks developers face when building mobile apps and PWAs. This guide will provide an introduction to the various tools available for managing the on-screen keyboard in your application.

inputmode

inputmode 属性允许开发者指定可以在输入中输入什么类型的数据。这将提示浏览器显示一个键盘，其中包含与用户可能输入的内容相关的按钮。例如，inputmode="email" 将显示带有 @ 键的键盘以及用于输入电子邮件的其他优化。

¥The inputmode attribute allows developers to specify what type of data might be entered into an input. This will prompt the browser to show a keyboard that includes buttons relevant to what the user may enter. For example, inputmode="email" will display a keyboard with the @ key as well as other optimizations for entering emails.

由于 inputmode 是全局属性，因此除了常规输入元素之外，它还可以用于 ion-input 和 ion-textarea 等 Ionic 组件。

¥Since inputmode is a global attribute, it can be used on Ionic components such as ion-input and ion-textarea in addition to regular input elements.

需要特定数据类型的输入应使用 type 属性。例如，需要电子邮件的输入应使用 type="email"，而不是指定 inputmode.。这是因为将输入的数据始终采用电子邮件的形式。另一方面，如果输入接受电子邮件或用户名，则使用 inputmode=”email” 是合适的，因为输入的数据并不总是电子邮件地址。

¥Inputs that require a certain data type should use the type attribute instead. For example, inputs that require an email should use type="email" rather than specifying an inputmode. This is because the data that will be entered is always going to be in the form of an email. On the other hand, if the input accepts an email or a username, using inputmode=”email” is appropriate because the data being entered is not always going to be an email address.

有关可接受值的列表，请参阅 输入模式文档。

¥For a list of accepted values, see the inputmode Documentation.

用法

¥Usage

注意

运行 Chrome 66+ 和 iOS Safari 12.2+ 的设备支持 inputmode 属性：https://caniuse.com/#search=inputmode

¥The inputmode attribute is supported on devices running Chrome 66+ and iOS Safari 12.2+: https://caniuse.com/#search=inputmode

enterkeyhint

enterkeyhint 属性允许开发者指定应为 "进入" 键显示什么类型的操作标签或图标。使用 enterkeyhint 让用户知道点击“Enter”键时会发生什么。此处应指定的值取决于用户正在执行的操作的上下文。例如，如果用户在搜索框中输入内容，开发者应确保输入内容为 enterkeyhint="search"。

¥The enterkeyhint attribute allows developers to specify what type of action label or icon should be shown for the "Enter" key. Using enterkeyhint lets the user know what will happen when they tap the “Enter” key. The value that should be specified here depends on the context of what the user is doing. For example, if the user is typing into a searchbox, developers should ensure that the input has enterkeyhint="search".

由于 enterkeyhint 是全局属性，因此除了常规输入元素之外，它还可以用于 ion-input 和 ion-textarea 等 Ionic 组件。

¥Since enterkeyhint is a global attribute, it can be used on Ionic components such as ion-input and ion-textarea in addition to regular input elements.

有关可接受值的列表，请参阅 Enterkeyhint 标准。

¥For a list of accepted values, see the enterkeyhint Standard.

用法

¥Usage

注意

运行 Chrome 77+ 和 iOS Safari 13.4+ 的设备支持 enterkeyhint 属性。

¥The enterkeyhint attribute is supported on devices running Chrome 77+ and iOS Safari 13.4+.

夜间模式

¥Dark Mode

默认情况下，键盘主题由操作系统决定。例如，如果在 iOS 上启用了夜间模式，即使你的应用的 CSS 中没有深色主题，应用中的键盘也会显示为深色主题。

¥By default the keyboard theme is determined by the OS. For example, if dark mode is enabled on iOS, the keyboard in your app will appear with a dark theme even if your application does not have a dark theme in its CSS.

当在移动网络浏览器中或作为 PWA 运行应用时，无法强制键盘以特定主题显示。

¥When running an app in a mobile web browser or as a PWA there is no way to force the keyboard to appear with a certain theme.

在 Capacitor 或 Cordova 中运行应用时，可以强制键盘以特定主题显示。有关此配置的更多信息，请参阅 Capacitor 键盘文档。

¥When running an app in Capacitor or Cordova, it is possible to force the keyboard to appear with a certain theme. For more information regarding this configuration, see the Capacitor Keyboard Documentation.

隐藏访问器栏

¥Hiding the Accessory Bar

当运行任何类型的基于网络的应用时，iOS 将在键盘上方显示一个附件栏。这允许用户移至下一个或上一个输入以及关闭键盘。

¥When running any kind of web based application, iOS will show an accessory bar above the keyboard. This allows users to move to the next or previous inputs as well as close the keyboard.

在移动网络浏览器中或作为 PWA 运行应用时，无法隐藏附件栏。

¥When running an app in a mobile web browser or as a PWA there is no way to hide the accessory bar.

在 Capacitor 或 Cordova 中运行应用时，可以隐藏附件栏。有关此配置的更多信息，请参阅 Capacitor 键盘文档。

¥When running an app in Capacitor or Cordova, it is possible to hide the accessory bar. For more information regarding this configuration, see the Capacitor Keyboard Documentation.

键盘生命周期事件

¥Keyboard Lifecycle Events

检测屏幕键盘的存在对于调整输入的位置非常有用，否则输入将被键盘隐藏。对于 Capacitor 和 Cordova 应用，开发者通常依赖原生键盘插件来监听键盘生命周期事件。对于在移动浏览器中运行或作为 PWA 运行的应用，开发者可以在支持的情况下使用 视觉视口 API。Ionic Framework 封装了这两种方法，并在 window 上发出 ionKeyboardDidShow 和 ionKeyboardDidHide 事件。ionKeyboardDidShow 的事件负载包含键盘高度的近似值（以像素为单位）。

¥Detecting the presence of an on-screen keyboard is useful for adjusting the positioning of an input that would otherwise be hidden by the keyboard. For Capacitor and Cordova apps, developers typically rely on native keyboard plugins to listen for the keyboard lifecycle events. For apps running in a mobile browser or as a PWA, developers can use the Visual Viewport API where supported. Ionic Framework wraps both of these approaches and emits ionKeyboardDidShow and ionKeyboardDidHide events on the window. The event payload for ionKeyboardDidShow contains an approximation of the keyboard height in pixels.

用法

¥Usage

JavaScript

window.addEventListener('ionKeyboardDidShow', ev => {
  const { keyboardHeight } = ev;
  // Do something with the keyboard height such as translating an input above the keyboard.
});

window.addEventListener('ionKeyboardDidHide', () => {
  // Move input back to original location
});

Angular

import { Platform } from '@ionic/angular';



...

constructor(private platform: Platform) {
  this.platform.keyboardDidShow.subscribe(ev => {
    const { keyboardHeight } = ev;
    // Do something with the keyboard height such as translating an input above the keyboard.
  });

  this.platform.keyboardDidHide.subscribe(() => {
    // Move input back to original location
  });
}

Angular (Standalone)

import { Platform } from '@ionic/angular/standalone';



...

constructor(private platform: Platform) {
  this.platform.keyboardDidShow.subscribe(ev => {
    const { keyboardHeight } = ev;
    // Do something with the keyboard height such as translating an input above the keyboard.
  });

  this.platform.keyboardDidHide.subscribe(() => {
    // Move input back to original location
  });
}

React

import { useKeyboardState } from '@ionic/react-hooks/keyboard';



...

const { isOpen, keyboardHeight } = useKeyboardState();

// Do something with the keyboard height such as translating an input above the keyboard

Vue

import { useKeyboard } from '@ionic/vue';


import { watch } from 'vue';

...

const { isOpen, keyboardHeight } = useKeyboard();

watch(keyboardHeight, () => {
  console.log(`Is Keyboard Open: ${isOpen.value}, Keyboard Height: ${keyboardHeight.value}`);
});

注意

对于在移动网络浏览器中运行或作为 PWA 运行的应用，键盘生命周期事件仅在 Chrome 62+ 和 iOS Safari 13.0+ 上受支持。

¥For apps running in a mobile web browser or as a PWA, Keyboard Lifecycle Events are only supported on Chrome 62+ and iOS Safari 13.0+.