How to Get Full Screen Dimensions for Responsive Design on HarmonyOS (ArkTS) Wearables using ohos.display?

#harmonyos #wearabledeviceui #responsiveuidesign #screendimensiondetection

Read the original article：How to Get Full Screen Dimensions for Responsive Design on HarmonyOS (ArkTS) Wearables using ohos.display?

Requirement Description

In HarmonyOS wearable applications, understanding and adapting to the full screen dimensions of devices is essential for delivering a high-quality user experience. Wearables come in diverse form factors, including round, square, and rectangular screens, each with different resolutions and densities. Without accurate knowledge of available screen space, UI elements such as buttons, text, and interactive components may not scale properly, causing usability issues or overlapping content. Considering full screen dimensions ensures responsive design, maintaining accessibility, visual consistency, and a seamless experience across all devices, while also supporting performance optimization and informed design decisions regarding element sizing and placement.

Background Knowledge

ohos.display is a HarmonyOS API that provides access to device screen metrics such as width, height, pixel density, and orientation. It allows developers to create responsive and adaptive UIs for wearable devices by dynamically adjusting layouts and interactive elements based on screen characteristics. Using ohos.display ensures UI consistency, proper scaling, and a seamless user experience across diverse wearable form factors.

Implementation Steps

For example, in our application, we use the device’s full screen dimensions to constrain and manage a gyroscope-controlled cursor within a circular area on HarmonyOS wearable devices. By referencing the screen width, the app ensures that cursor movements stay within visible bounds, preventing overflow or clipping, and providing a consistent, responsive, and visually intuitive experience across different wearable form factors.

In line with this objective, the implementation steps are as follows:

Retrieve Display Dimensions:
- Access the device’s screen width and height to define the circular boundary and its center.
Initialize Sensors:
- Register accelerometer and gyroscope sensors to receive real-time motion data.
Map Sensor Input to Cursor Movement:
- Convert accelerometer readings into X and Y position updates, applying a sensitivity factor.
Apply Boundary Constraints:
- Calculate the cursor’s distance from the circle center and prevent it from exceeding the circular area.
Provide Visual Feedback:
- Change the circle’s color when the cursor approaches the edge to indicate proximity.
Update UI Dynamically:
- Continuously render the cursor and circular boundary on the screen, ensuring responsiveness across different wearable devices.
Cleanup Sensors:
- Unregister accelerometer and gyroscope sensors when the component is no longer active to conserve resources.

Code Snippets / Configuration

import { sensor } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { promptAction } from '@kit.ArkUI';
import display from '@ohos.display';

These imports bring in the necessary modules for sensors, UI feedback, error handling, and importantly, screen metrics through @ohos.display. The display module allows the application to retrieve the device’s screen width, which is critical for defining responsive UI elements such as the circular boundary for the gyroscope-controlled cursor.

aboutToAppear(): void {
    this.circleDiameter = display.getDefaultDisplaySync().width / 2;
    this.circleRadius = this.circleDiameter / 2;
    this.circleCenterX = this.circleRadius;
    this.circleCenterY = this.circleRadius;
    this.startSensors();
}

When the component appears, the full screen width is obtained from ohos.display and used to calculate the circle’s diameter and radius. The circle center coordinates are then derived from this radius. This ensures that the circular movement area for the cursor is responsive, automatically adjusting to different screen sizes and form factors, and serves as the basis for constraining gyroscope-based movements.

@State cursorX: number = 111.5;
@State cursorY: number = 111.5;

The cursor’s initial position is set approximately at the circle’s center. Because the circle’s center is dynamically calculated using the screen width, the cursor will always start in a consistent position regardless of device size. This approach ensures that the cursor placement remains responsive and visually correct across all wearable devices.

const distanceFromCenter = Math.sqrt(
  Math.pow(newX + this.dotRadius - this.circleCenterX, 2) +
  Math.pow(newY + this.dotRadius - this.circleCenterY, 2)
);
if (distanceFromCenter > this.circleRadius - this.dotRadius) { ... }

Gyroscope input is converted into cursor X/Y positions, and the distance from the circle center is calculated. If the cursor exceeds the circle radius, it is projected back onto the perimeter, preventing overflow. Because the circle radius is derived from the screen width, the cursor’s movement area automatically scales for responsive behavior on different wearable devices.

const distanceToEdge = this.circleRadius - distanceFromCenter;
if (distanceToEdge <= this.edgeThreshold) { this.circleColor = Color.Blue; }

This checks the cursor’s proximity to the circle edge and changes the circle’s stroke color as visual feedback. Using the responsive circle radius ensures that the feedback triggers correctly across all screen sizes, enhancing usability without manual adjustments for different devices.

Stack() {
    Circle()
        .width(this.circleDiameter)
        .height(this.circleDiameter)
        .fill(Color.Transparent)
        .stroke(this.circleColor)
        .strokeWidth(3);
    Circle()
        .width(15)
        .height(15)
        .position({ x: this.cursorX, y: this.cursorY })
        .fill(Color.Red)
        .opacity(0.8);
}
.width('100%')
.height('100%')
.backgroundColor('#1a1a1a')

The circular boundary and cursor are rendered on the screen using ArkUI components. The circle’s diameter is based on the screen width retrieved from ohos.display, ensuring that the movement area scales responsively. The cursor is dynamically positioned based on gyroscope input but constrained within the circle. The Stack fills the screen, guaranteeing a consistent and adaptive UI layout across wearable devices with different screen shapes and resolutions.

Test Results

The following screenshots show an application that uses the relevant ohos.display and sensor kit, featuring boundaries drawn according to the watch’s screen dimensions and visual feedback such as the screen color changing when the ball touches the edges.