Web Component focus management

Focus Management with Web Components in HarmonyOS Next

Overview

Developers can effectively manage the focus and defocus of Web components using the focus management capabilities of Web components. Additionally, they can utilize the W3C standard interfaces on the H5 side to manage the focus and defocus of the unique interactive elements on the webpage interface.

Common Interfaces for Focus Control

Web Component and ArkUI Component Focus Control

• requestFocus: Actively request focus for the Web component. When there are multiple components within an application, developers can use the requestFocus interface of the Web component to transfer focus to it.
• Change Web Component Style Based on Focus: Modify the component's style (e.g., border, background color) based on focus events to provide visual and interactive feedback.

Focus Control of H5 Elements within Web Components

• tabindex Attribute: Manage element focus within the Web component. Define the focus order of elements by setting the tabindex attribute. Setting tabindex to "-1" allows the element to be focused via script while controlling its visibility in CSS.
• Update Focus Position with Keyboard Events: Listen for keyboard events (e.g., Tab key) to update the focus position of elements within the Web component based on user actions.
• Change Element Style Based on Focus: Add styles to focused elements (e.g., border, background color) to provide visual and interactive feedback.

Basic Concepts

For detailed explanations of Web component focus, focus chain, and focus transfer, please refer to the ArkUI Focus Basic Concepts.

• Focus:

  • Component Focus: The only interactive element on the current application interface.
  • Web Element Focus: The only interactive element on the current webpage interface.
  • When users interact with applications using non-pointing input devices like keyboards, remote controls, or joysticks, focus-based navigation and interaction are crucial.

• Focus Transfer:

  • Component Focus Transfer: The behavior of focus moving between components within the application. This process is transparent to users, and developers can capture these changes by listening to onFocus (focus acquisition) and onBlur (focus loss) events.
  • Web Element Focus Transfer: The behavior of focus moving between elements within the webpage. This behavior follows the W3C standard, and developers can capture these changes by listening to focus (triggered when an element gains focus) and blur (triggered when an element loses focus) events.

Web Component Focus Transfer Specifications

Based on the triggering method, focus transfer can be divided into active and passive focus transfer. For detailed specifications, refer to the ArkUI Focus Transfer Specifications.

• Active Focus Transfer: Focus movement caused by developer or user actions. This includes:

  • Using requestFocus to request focus.
  • Focus transfer using external keyboard keys (TAB/Shift+TAB).
  • Focus acquisition by clicking (gesture/mouse/touchpad).

• Passive Focus Transfer: Focus movement due to system actions or other operations without direct developer intervention. This is the default behavior of the focus system.

Scenarios for Passive Focus Transfer

• Component Removal: When the Web component with focus is removed, the system transfers focus to the adjacent sibling component following the principle of first backward then forward. If no sibling component can gain focus, the focus is released, and the parent component is prompted to take over focus management.
• Property Change: If the focusable or enabled property of the focused component is set to false, or the visibility property is set to invisible, the system automatically transfers focus to another focusable component, following the same transfer method as component removal.
• Web Component Invisibility: ArkWeb loses and regains focus during application foreground/background switching, page switching, Navigation navigation, etc.
• Web Component Loading Webpage: ArkWeb gains focus by default when loading a webpage via src, loadUrl, loadData. However, if the Web component is in a non-focusable state at this time, focus acquisition will fail (common reasons for non-focusable states include: parent component non-focusable during transition animations, application-side setting of non-focusable properties for the Web component or its parent component, etc.). The application side can call the requestFocus interface again to attempt to make the Web component focusable. Once focus acquisition is successful, both the application-side onFocus and W3C focus events are triggered.
• autofocus Style: Elements with the autofocus style gain focus by default when the webpage finishes loading. If the element supports text input, the input box will have a blinking cursor, but the soft keyboard will not be activated.
• Menu Pop-up: ArkUI overlay attribute type components default to grabbing focus. In scenarios where ArkWeb is combined with such components (e.g., menu, datepicker, timepicker, dropdown, dialog, etc.), ArkWeb will lose focus.

Focus Control Between Web Components and ArkUI Components

• onFocus: A general focus acquisition callback interface on the application side. When a component bound to this interface gains focus, the callback is triggered.
• onBlur: A general focus loss callback interface on the application side. When a component bound to this interface loses focus, the callback is triggered.
• requestFocus: An interface for components to actively request focus.

Example

requestFocus allows application developers to actively control focus transfer to the Web component. The onFocus and onBlur interfaces are typically used in pairs to listen for component focus changes.

// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();
  controller2: webview.WebviewController = new webview.WebviewController();
  @State webborderColor: Color = Color.Red;
  @State webborderColor2: Color = Color.Red;

  build() {
    Column() {
      Row() {
        Button('web1 requestFocus')
          .onClick(() => {
            try {
              this.controller.requestFocus();
            } catch (error) {
              console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
            }
          });
        Button('web2 requestFocus')
          .onClick(() => {
            try {
              this.controller2.requestFocus();
            } catch (error) {
              console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
            }
          });
      }
      Web({ src: 'https://www.example.com', controller: this.controller })
        .onFocus(() => {
          this.webborderColor = Color.Green;
        })
        .onBlur(() => {
          this.webborderColor = Color.Red;
        })
        .margin(3)
        .borderWidth(10)
        .borderColor(this.webborderColor)
        .height("45%")

      Web({ src: 'https://www.example.com', controller: this.controller2 })
        .onFocus(() => {
          this.webborderColor2 = Color.Green;
        })
        .onBlur(() => {
          this.webborderColor2 = Color.Red;
        })
        .margin(3)
        .borderWidth(10)
        .borderColor(this.webborderColor2)
        .height("45%")
    }
  }
}

Explanation

• requestFocus: Actively requests focus for the Web component.
• onFocus and onBlur: These interfaces are used to listen for focus changes on the Web component. When the component gains or loses focus, the corresponding callback is triggered, and the border color of the Web component is updated accordingly.