Web components interface with the soft keyboard

Handling Soft Keyboard with Web Components in HarmonyOS Next

Overview

Developers can integrate soft keyboards with Web components to manage the display and interaction of the system soft keyboard, as well as to implement custom soft keyboard functionalities. This is particularly useful in scenarios such as:

1. Pulling up the system soft keyboard for text input: When users click on an input field on a webpage, the system's default soft keyboard (input method) appears at the bottom of the screen, allowing users to input text, which is then displayed in the input field.
2. Customizing the return key type of the soft keyboard: Applications can specify different types of return keys for the soft keyboard when an input field is focused. For example, "Done", "Next", "Submit", etc.
3. Soft keyboard avoidance: On mobile devices, applications can set different soft keyboard avoidance modes for Web pages, such as "pan", "resize", or "none".
4. Custom soft keyboard input: Applications can use custom input methods to input text on Web pages, replacing the system soft keyboard.

W3C Standard Support for Input Control Attributes

To ensure good interaction between Web pages and system or custom soft keyboards, ArkWeb adheres to and implements the following input control attributes from the W3C specifications:

type Attribute

The type attribute defines the type of the input element, affecting input validation, display, and keyboard type. Common type values include:

type Value	Description
text	Default. Normal text input
number	Numeric input
email	Email address input
password	Password input
tel	Telephone number input
url	URL input
date	Date picker
time	Time picker
checkbox	Checkbox
radio	Radio button
file	File upload
submit	Submit button
reset	Reset button
button	Normal button

inputmode Attribute

The inputmode attribute is used to configure the type of input method.

inputmode Value	Description
decimal	Displays a numeric keyboard with a comma key
email	Text keyboard with keys typically used for email addresses, such as @
none	No keyboard should appear
numeric	Displays a numeric keyboard
search	Text keyboard with an enter key typically displayed as go
tel	Displays a numeric keyboard with keys like +, *, and #
text	Default. Text keyboard
url	Text keyboard with keys typically used for URLs, such as . and /, and a special .com key

enterkeyhint Attribute

The enterkeyhint attribute specifies the display of the return key on the virtual keyboard on mobile devices.

enterkeyhint Value	Description
enter	Displays the default return key
done	Indicates completion of input
go	Indicates navigation or execution
next	Moves to the next input field
previous	Moves to the previous input field
search	Executes a search
send	Sends a message

Notes

• When users click on an input field on a webpage, the system's default soft keyboard appears at the bottom of the screen, allowing text input.
• The type attribute is more versatile, affecting not only keyboard display but also input validation and element appearance.
• The inputmode attribute is primarily used to optimize the keyboard input experience on mobile devices and does not change the basic behavior or validation of the input.

Setting Soft Keyboard Avoidance Mode

On mobile devices, you can set the soft keyboard avoidance mode for Web pages.

(1) Set the Soft Keyboard Avoidance Mode in the Application Code

// EntryAbility.ets
import { KeyboardAvoidMode } from '@kit.ArkUI';
import { hilog } from '@kit.PerformanceAnalysisKit';

onWindowStageCreate(windowStage: window.WindowStage) {
  hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');

  windowStage.loadContent('pages/Index', (err, data) => {
    let keyboardAvoidMode = windowStage.getMainWindowSync().getUIContext().getKeyboardAvoidMode();
    // Set the virtual keyboard to resize the page height by subtracting the keyboard height
    windowStage.getMainWindowSync().getUIContext().setKeyboardAvoidMode(KeyboardAvoidMode.RESIZE);
    if (err.code) {
      hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
      return;
    }
    hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
  });
}

(2) Pull Up the Soft Keyboard in the Web Component

<!-- index.html -->
<!DOCTYPE html>
<html>
  <head>
    <title>Test Web Page</title>
  </head>
  <body>
    <h1>DEMO</h1>
    <input type="text" id="input_a">
  </body>
</html>

// Index.ets
import { webview } from '@kit.ArkWeb';

@Entry
@Component
struct KeyboardAvoidExample {
  controller: webview.WebviewController = new webview.WebviewController();

  build() {
    Column() {
      Row().height("50%").width("100%").backgroundColor(Color.Gray)
      Web({ src: $rawfile("index.html"), controller: this.controller })
      Text("I can see the bottom of the page").width("100%").textAlign(TextAlign.Center).backgroundColor(Color.Pink).layoutWeight(1)
    }.width('100%').height("100%")
  }
}

Explanation

• Keyboard Avoidance Modes:
  • Resize Mode: The application window height is resized to exclude the soft keyboard, and the ArkWeb component follows the ArkUI layout.
  • Offset Mode: The application window height remains unchanged, and the ArkWeb component adjusts based on its own avoidance mode.