Interacting with Applications Using Gestures

On mobile or touch-enabled web applications, users interact with web pages through gestures. ArkWeb supports the recognition of common gestures, such as touch and hold, swipe, and tap, providing a rich user interaction experience.

ArkWeb Gesture Recognition

ArkWeb receives the ArkUI touch event and identifies the gesture. For details about the distribution policy of touch events, see Basic Interaction Principles. ArkWeb gestures comply with the touch events, UI events, and pointer events defined by the W3C standard.

The following table lists identifications of common events.

ArkWeb Gestures and ArkUI Gestures

ArkUI provides gesture binding while ArkWeb has independent gesture recognition. Therefore, you need to distinguish these two types of gestures.

• ArkWeb gestures: automatically generated by Web components upon receiving touch events. These gestures are used on web pages.
• ArkUI gestures: received by and used on the Web component. ArkUI gestures are not directly used on web pages.

The following uses zoom as an example to describe the differences between the two gestures:

• When two fingers are pinched on the web page, the content in the Web component is zoomed in or out. This is because ArkWeb identifies the pinch event and applies it to the web page.
• If a user pinches three fingers together, the Web component itself scales. This is because ArkWeb receives the Pinch Gesture identified by ArkUI and executes the bound callback function. In addition, ArkWeb supports the scale method, which can be used to adjust the zoom ratio of the Web component.

NOTE

This example is used only to describe the differences between ArkUI gestures and ArkWeb gestures. You are not advised to use this method to scale Web components.

import { webview } from '@kit.ArkWeb';

@Entry
@Component
struct Index {
  @State scaleValue: number = 1;
  @State pinchValue: number = 1;
  controller: webview.WebviewController = new webview.WebviewController();

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
      // Bind the zoom ratio to the component. You can change the zoom ratio to zoom in or out the component.
        .scale({ x: this.scaleValue, y: this.scaleValue, z: 1 })
        .zoomAccess(true)
        .gesture(
          // Bind the pinch gesture triggered by three fingers to the component.
          PinchGesture({ fingers: 3 })
            .onActionStart((event: GestureEvent|undefined) => {
              console.info('Pinch start');
            })
            // Obtain the zoom ratio through the callback function when the pinch gesture is triggered, and then change the zoom ratio of the component.
            .onActionUpdate((event: GestureEvent|undefined) => {
              if(event){
                this.scaleValue = this.pinchValue * event.scale;
                console.info(`Pinch update: ${this.scaleValue}`);
              }
            })
            .onActionEnd(() => {
              this.pinchValue = this.scaleValue;
              console.info('Pinch end');
            })
        )
    }
  }
}

ArkWep Gesture Judgment

• ArkUI gestures

  ArkWeb consumes some ArkUI gestures, for example, pan gesture. If you want to process these gestures by yourself instead of ArkWeb, see Gesture Conflict Handling.

• ArkWeb gestures

  ArkWeb gestures are generated after the Web component receives touch events. You can use either of the following methods to judge ArkWeb gestures:

  1. Do not send touch events to the Web component. For details, see Hit Testing.
  2. Send the TouchCancel event to the Web component. For details about the C APIs, see OH_ArkUI_TouchRecognizer_CancelTouch. For details about the sample, see NdkGestureSetting.

FAQs

How do I disable the zoom gesture?

The Web component provides the zoomAccess API to control whether to enable zooming. You can also use the user-scalable attribute on the web page to control zooming. For details, see Zooming Web Pages.

How do I enable the Web component to return to the previous web page following a swipe gesture?

Solution

Override the onBackPress API to define the return logic and use WebviewController to determine whether to return to the previous web page.

Example

import { webview } from '@kit.ArkWeb';

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

  build() {
    Column() {
      Web({ src: 'https://www.example.com', controller: this.controller })// Replace the URL with the actual URL.
    }
  }

  onBackPress() {
    // Check whether a specific number of steps forward or backward can be performed on the current page. A positive number indicates forward, and a negative number indicates backward.
    if (this.controller.accessStep(-1)) {
      this.controller.backward(); // Return to the previous web page.
      // Execute the custom return logic.
      return true;
    } else {
      // Execute the default return logic to return to the previous page.
      return false;
    }
  }
}

Why cannot I interact with the web page after it is loaded?

The web page may determine its behavior based on other platforms' User-Agent. To solve this problem, you can set a custom User-Agent in the Web component. For example:

import { webview } from '@kit.ArkWeb';

@Entry
@Component
struct Index {
  private webController: webview.WebviewController = new webview.WebviewController();
  build(){
    Column() {
      Web({
        src: 'https://www.example.com',
        controller: this.webController,
      }).onControllerAttached(() => {
        // Customize User-Agent.
        let customUA = 'Mozilla/5.0 (Phone; Android; HarmonyOS 5.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Mobile Safari/537.36';
        this.webController.setCustomUserAgent(customUA);
      })
    }
  }
}