键盘

在构建移动应用和渐进式网页应用（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 是全局属性，它可以用于常规输入元素之外的 Ionic 组件，例如 ion-input 和 ion-textarea。

🌐 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.

有关可接受值的列表，请参见 inputmode 文档。

用法

🌐 Usage

note

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

enterkeyhint

enterkeyhint 属性允许开发者指定“回车”键应显示哪种操作标签或图标。使用 enterkeyhint 可以让用户知道在点击“回车”键时会发生什么。这里应指定的值取决于用户正在执行的操作的具体情况。例如，如果用户正在输入搜索框内容，开发者应确保输入具有 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 是全局属性，它可以用于 Ionic 组件，如 ion-input 和 ion-textarea，除此之外也可以用于常规输入元素。

🌐 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 标准。

用法

🌐 Usage

note

enterkeyhint 属性在运行 Chrome 77 及以上版本和 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 键盘文档。

隐藏访问器栏

🌐 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 键盘文档。

键盘生命周期事件

🌐 Keyboard Lifecycle Events

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

用法

🌐 Usage

JavaScript

window.addEventListener('ionKeyboardDidShow', event => {
  const { keyboardHeight } = event;
  // 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(event => {
    const { keyboardHeight } = event;
    // 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(event => {
    const { keyboardHeight } = event;
    // 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}`);
});

note

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