目录

PC App Development

Overview

PCs play an important role in daily life and are also indispensable to the all-scenario experience of HarmonyOS 1+8 devices.

PCs have the following features:

Currently, the main PC products include the MateBook Pro series.

Product Name

Image

MateBook Pro series

This topic provides the development guidelines for improving user experience of PC apps. For details about the basic common capabilities of multi-device development, see Overview.

Product Hardware Information

This topic describes the screen size and camera hardware parameters of PCs.

[h2]Screen Specification Information

The following uses MateBook Pro as an example to describe the effect, resolution, and horizontal and vertical breakpoints. For details, see the following table.

  

MateBook Pro (Laptop)

External Display

Effect

Display ID

0

Main display: 0

External display: depending on the connected MateBook Pro port

Display Orientation

Landscape (LANDSCAPE)

NA

Resolution (px)

3120*2080

Main display: 3120 × 2080

External display: depending on the resolution of the external display

Resolution (vp, Rounded Down)

1642*1094

Main display: 1642 × 1094

External display: depending on the resolution of the external display

Available Display Width and Height (px)

3120*1955

Main display: 3120 × 1955

External display: depending on the resolution of the external display

Available Screen Width and Height (vp, Rounded Down)

1642*1028

Main display: 1642 × 1028

External display: depending on the resolution of the external display

Horizontal and Vertical Breakpoints

xl for horizontal breakpoints and sm for vertical breakpoints

Main display: xl for horizontal breakpoints and sm for vertical breakpoints

External display: depending on the resolution of the external display

[h2]Camera Hardware Information

The default camera lens installation angle is preset for the camera of PCs. When using the camera, you need to consider the lens angle and device rotation angle. For details, see Preview Rotation Angle. When the screen orientation is the same, the angle of the front camera and the rotation angle of the preview stream to be set are as follows. Currently, the camera of PCs (for example, MateBook Pro) cannot be rotated.

Screen Rotation Angle (rotation)

0 (0°)

1 (90°)

2 (180°)

3 (270°)

Effect

NA

NA

NA

Front Camera Lens Installation Angle

270°

NA

NA

NA

Preview Rotation Angle

270°+0°=270°

NA

NA

NA

Rear Camera Lens Installation Angle

No rear camera

Innovation and Experience Improvement

[h2]Performance Optimization

Performance optimization for PC apps directly impacts user experience, running efficiency, and hardware resource utilization. HarmonyOS provides the DevEco Profiler tool to support full-dimension performance monitoring (CPU, GPU, memory, frame rate, power consumption, and network) and code-level issue locating and analysis, helping you quickly detect and optimize performance bottlenecks. For details about how to use the performance tools, see Introduction to Performance Optimization Tools. For details about the performance optimization cases, see Performance Optimization Cases.

For critical threads in your PC app, you can increase their task scheduling priority to ensure that they have sufficient contiguous execution time and resources. This helps maintain smooth app performance and optimizes user experience. For details, see Setting Thread Priority in Heavy-Load Scenarios.

[h2]Focus Navigation

PCs are equipped with keyboards. Your app must support focus navigation through the keyboard and configure visual effects for focus to clearly indicate the current focus position, ensuring a smooth interaction experience. For details about the development solution, see Focus Events.

[h2]Audio Focus Adaptation

Foreground and background apps on PCs need to handle audio focus in four key areas: Process of Preempting Audio Focus, Correctly Configuring the Audio Stream Type, Customizing the Focus Strategy, and Correctly Handling Focus Interrupt Events.

The management mechanism on PCs is similar to that on other devices, with the main difference being the default system strategies. You can refer to Customizing the Focus Strategy to learn the differences between PCs and other devices.

[h2]Floating Window

A floating window is a special app window on PCs, with the window type being WindowType.TYPE_FLOAT. You can create a floating window based on an existing task to keep it always on top of all app windows in the foreground. Even if the app that created the floating window is sent to the background, the floating window can still remain in the foreground.

Compatibility Mode

This topic describes the running rules, release configuration, and debugging methods of the compatibility mode on the PC, as well as the adaptation key points of the camera, APIs, file access, and hardware capabilities.

[h2]Compatibility Running

Compatibility running allows you to port mobile/tablet apps for PC deployment.

Window mode for compatibility running on the PC

When a mobile/tablet app runs on the PC in compatibility mode, the default display rules of the window are as follows:

Compatible apps cannot be maximized.

Trustlist policy in window mode

The operating system has a built-in trustlist function to manage the default display ratio of apps, including 18:9, 1:1, and full-screen.

[h2]Project Configuration for Compatibility Running

To ensure that an app adapted for mobile phones/tablets can run on a PC, remove support for 2-in-1 devices from the module.json5 file of the app's entry module.

"deviceTypes": [
    "default",
    "tablet",
    "2in1" (removed)
]

The configuration file with the same name of the module on which the entry module depends also needs to be modified.

[h2]App Compatibility Test

In the early stage of ecosystem development, PC apps are mainly released in compatibility mode. As the ecosystem gradually matures, the system provides corresponding settings to manage compatibility policies, facilitating continuous adaptation to the landscape mode on PCs.

After installing the app, go to Settings > Display & brightness > App scaling options and adjust the app display ratio to the original ratio to exit the compatibility mode, facilitating debugging.

[h2]Check or Adaptation Items

In principle, apps capable of compatibility running only require small adaption on some differences. For details about the adaptation requirements, see the following description.

Common Device Adaptation Issues

[h2]Device Type Differentiation

How to distinguish between MateBook Pro and MateBook Fold?

[h2]Package Management Policy

The management policy of the HAP on the PC needs to be flexibly selected based on the application scenario to balance the consistency and personalization, and ensure development efficiency and user experience. The specific solutions are as follows:

For details, see the content related to the product customization layer in Layered Architecture Design.

[h2]Window Adaptation

What should I do if the app cannot detect the available area change in a timely manner when the window changes?

Problem description: The app cannot detect the available area change in a timely manner or there is a delay in detecting the change. As a result, the app directly calls moveWindowTo() or resize() to adjust the window size or position, causing abnormal window size or position.

Solution: Use any of the following methods to solve the problem:

What should I do if an exception occurs when the free-from multi-window adapts to the PC window?

Problem description: When the free-from multi-window is adapted to PCs, the following issues may occur:

Solution

What should I do if the app flickers when the window is started?

Possible cause: The window position and size set in the metadata tag in the module.json5 configuration file are inconsistent with the window parameters set in the layout of onWindowStageCreate().

Solution: Ensure that the metadata configuration in module.json5 is the same as the window position and size in onWindowStageCreate().

"abilities": [
  {
    "name": "EntryAbility",
    "srcEntry": "./ets/entryability/EntryAbility.ets",
    "supportWindowMode": [
      "fullscreen"
    ],
    "metadata": [
      {
        "name": "ohos.ability.window.height",
        "value": "600"
      },
      {
        "name": "ohos.ability.window.width",
        "value": "600"
      },
      {
        "name": "ohos.ability.window.left",
        "value": "left"
      },
      {
        "name": "ohos.ability.window.top",
        "value": "top"
      }
    ],
    // ...
  },
  // ...
],
onWindowStageCreate(windowStage: window.WindowStage): void {
  // Main window is created, set main page for this ability
  hilog.info(DOMAIN, TAG, '%{public}s', 'Ability onWindowStageCreate');
  try {
    let mainWindow = windowStage.getMainWindowSync();
    let displayId = mainWindow.getWindowProperties().displayId;
    let displayClass = display.getDisplayByIdSync(displayId);
    displayClass.getAvailableArea().then(() => {
      mainWindow.resize(mainWindow.getUIContext().px2vp(600), mainWindow.getUIContext().px2vp(600))
        .catch((err: BusinessError) => {
          hilog.error(DOMAIN, TAG, '%{public}s',
            `Failed to change the window size. Code: ${err.code}, message: ${err.message}`);
        });
      mainWindow.moveWindowTo(0, 0).catch((err: BusinessError) => {
        hilog.error(DOMAIN, TAG, '%{public}s',
          `Failed to move the window. Code: ${err.code}, message: ${err.message}`);
      });
    }).catch((err: BusinessError) => {
      hilog.error(DOMAIN, TAG, '%{public}s',
        `Failed to get the available area in this display. Code: ${err.code}, message: ${err.message}`);
    })
  } catch (err) {
    hilog.error(DOMAIN, TAG, '%{public}s',
      `Failed to move the window. Cause code: ${err.code}, message: ${err.message}`);
  }
  windowStage.loadContent('pages/Index', (err) => {
    if (err.code) {
      hilog.error(DOMAIN, TAG, 'Failed to load the content. Cause: %{public}s', err);
      return;
    }
    hilog.info(DOMAIN, TAG, 'Succeeded in loading the content.');
  });
}