App Multiplier

Overview

App Multiplier is a system-level compatibility solution that implements the split-view display for wide-screen and large-screen devices based on the standard configuration when apps are not adapted to the split-view layout. When App Multiplier is enabled and the split-view display is used, two pages are displayed in one window at the same time. By default, each page occupies half of the window, as shown in the following figure. The home page is displayed on the left, and the page routing and redirection occur only on the right. The details page after redirection is displayed on the right. Starting from API version 23, developers can configure this feature.

App Multiplier is applicable to apps that require frequent page switching, such as office, email, IM, and e-commerce apps. Currently, App Multiplier supports two routing modes: navigation mode and shopping mode. The following uses a shopping app running on a dual-fold phone as an example:

• Navigation mode: The home page (product category page) on the left remains unchanged, and the products of the selected category or the details of a specific product are displayed on the right. Subsequent operations are performed on the right.
• Shopping mode: During page routing and redirection, the page on the right is always pushed to the left. The page at the top of the navigation stack is displayed on the right, and the page next to the top page is displayed on the left.

This topic is intended for intermediate and senior developers. Before learning this topic, complete the following preparations:

1. Environment: Install the latest DevEco Studio. Ensure that the SDK version is 6.1.0(23) or later.
2. Knowledge: Understand the basics of HarmonyOS development and master the knowledge of split-view layout and setting component navigation and page routing.

This topic covers the following content:

1. How to Develop: describes the complete adaptation process of App Multiplier for API version 23 and later versions.
2. Configuration Description: explains the meanings, value ranges, and setting rules of key parameters in the App Multiplier core configuration file, providing clear and standard setting guidance for developers.
3. Typical Development Scenarios: provide reusable solutions for high-frequency App Multiplier use scenarios based on the shopping apps implemented using Navigation.
4. FAQs: sort out high-frequency issues in App Multiplier development, analyze the main causes of these issues, and provide solutions and suggestions to help developers efficiently resolve issues in practice.
5. Sample Code: provides project code that can be directly run, downloaded by developers, and used together with this document.

How to Develop

1. Add the configuration file.

   Create the configuration file easy_go.json of the compatibility solution in the profile directory. The file name is an example and can be customized. Add the easyGo field to the module.json5 configuration file. This field points to the easy_go.json configuration file to be referenced. Currently, this configuration can be performed only in the entry module. After the configuration, it takes effect at the app level.

   

2. Configure App Multiplier attributes in the easy_go.json file. For details, see Configuration Description.

Configuration Description

easy_go.json is a standard object file in JSON format. It consists of two layers. The first layer configures the device type, and the second layer configures the display mode for the corresponding device type.

Device Type

{ 
  "common": {},
  "phone": {},
  "tablet": {}
}

Display Mode

The second layer configures the displayModeOptions field, which indicates the display mode of App Multiplier. The internal fields are as follows:

Internal fields of wideWindowMode and squareWindowMode:

The following table describes the fields that can be contained in routerSplitOptions and navigationSplitOptions.

navigationSplitOptions can contain the following additional fields:

Internal fields of wideSplit and squareSplit:

Internal fields of splitDividerColor:

Configuration Example

1. Configure the App Multiplier effect for common devices using Router.
   • Configure the App Multiplier effect for common devices through common.
   • Set wideWindowMode and squareWindowMode to routerSplit, indicating that the app routing is implemented by the Router component.
   • Configure the routerSplitOptions field and set the home page, related page, and full-screen page as required.

   {
     "common": {
       "displayModeOptions": {
         "wideWindowMode": "routerSplit",
         "squareWindowMode": "routerSplit",
         "routerSplitOptions": {
           "homePage": "pages/Index",
           "relatedPage": "pages/CategoryPage",
           "fullScreenPages": [
             "pages/FullScreenImagePage",
           ],
           "supportLandscapeFullscreen": true,
           "enableReducedContainerSize": true
         }
       }
     }
   }

2. Configure the App Multiplier effect for common devices using Navigation.
   • Configure the App Multiplier effect for common devices through common.
   • Set the wideWindowMode and squareWindowMode fields to navigationSplit, indicating that the app routing is implemented by the Navigation component.
   • Configure the navigationSplitOptions field and set fields such as the home page, related page, full-screen page, and routing mode as required. Set the left-to-right screen ratio to 1:2 for rectangular windows of tablets and triple-fold phones, and to 1:1 for square windows of dual-fold phones.

   {
     "common": {
       "displayModeOptions": {
         "wideWindowMode": "navigationSplit",
         "squareWindowMode": "navigationSplit",
         "navigationSplitOptions": {
           "homePage": "navBar",
           "relatedPage": "CategoryPage",
           "fullScreenPages": [
             "FullScreenImagePage"
           ],
           "supportLandscapeFullscreen": true,
           "enableReducedContainerSize": true,
           "wideSplit": {
             "ratio": "1 | 2"
           },
           "squareSplit": {
             "ratio": "1 | 1"
           },
           "mode": 0,
           "splitDividerColor": {
             "light": "#33FFFFFF",
             "dark": "#33000000"
           },
           "drawableRectHook": true,
           "enableInSplitScreen": true
         }
       }
     }
   }

3. The following uses the Navigation component as an example to describe how to disable App Multiplier for tablets.
   • Add tablet configurations.
   • Set the wideWindowMode and squareWindowMode fields to original to disable all compatible running of the window display mode.

   {
     "common": {
       "displayModeOptions": {
         "wideWindowMode": "navigationSplit",
         "squareWindowMode": "navigationSplit",
         "navigationSplitOptions": {
           "homePage": "CategoryPage",
           "fullScreenPages": [
             "FullScreenImagePage"
           ],
           "supportLandscapeFullscreen": true,
           "enableReducedContainerSize": false
         }
       }
     },
     "tablet": {
       "displayModeOptions": {
         "wideWindowMode": "original",
         "squareWindowMode": "original"
       }
     }
   }

Typical Development Scenarios

With a shopping app implemented using the Navigation component as an example, this topic describes four typical scenarios in App Multiplier adaptation development and how to perform configuration through the easy_go.json file.

Configuring Home Page and Related Page

Scenario

By default, the system identifies a page of the app as the home page. However, the home page may fail to be accurately identified with this mechanism in some scenarios. You are advised to configure the home page. If necessary, you can also configure the related page.

For example, in a shopping app, you can set the home page as the main page and the first product category page as the related page.

How to Implement

App Multiplier provides the capability of configuring the home page and related page. Set the home page using homePage and the related page using relatedPage.

How to Develop

1. In the easy_go.json file, set homePage to navbar, indicating that the Navigation home page is set as the home page. Set relatedPage to CategoryPage, indicating that the category page is set to the related page. The configuration file is as follows:

{
  "common": {
    "displayModeOptions": {
      "wideWindowMode": "navigationSplit",
      "squareWindowMode": "navigationSplit",
      "navigationSplitOptions": {
        "homePage": "navBar",
        "relatedPage": "CategoryPage"
      }
    }
  }
}

Requesting Full-Screen Display During Route Redirection

Scenario

On the product details page, to clearly display product details, the product image needs to be displayed in full screen after a user taps the image.

How to Implement

App Multiplier provides the full-screen page capability, which allows you to specify a full-screen page using the fullScreenPages field. After the configuration, the corresponding page will temporarily exit the split-view mode and switch to the full-screen view. When the page is hidden, the split-view mode is restored.

How to Develop

1. Add the image browsing page to the fullScreenPages field in the App Multiplier configuration file.

{
  "common": {
    "displayModeOptions": {
      ...
      "fullScreenPages": [
         "FullScreenImagePage"
      ],
    }
  }
}

Requesting Landscape Display During Route Redirection

Scenario

1. On the product details page, images of parameter comparison and configuration table often need to be displayed in landscape mode because the font size is too small in portrait mode.

How to Implement

App Multiplier supports full-screen display of pages in landscape mode by configuring the supportLandscapeFullScreen field. After this parameter is set to true in the easy_go.json file, when the app requests landscape mode, the split-view mode exits and the page is displayed in full screen.

How to Develop

1. In the easy_go.json file, set the supportLandscapeFullScreen attribute to true. After the configuration, when the app requests landscape mode, it will exit the split-view mode and switch to the full-screen view.

{
  "common": {
    "displayModeOptions": {
      ...
      "supportLandscapeFullScreen": true
    }
  }
}

Enabling the Virtual Container Capability

Scenario

When App Multiplier is enabled and the split-view display is used, two pages are displayed in one window at the same time. By default, each page occupies half of the window. If the window width is used for the element layout on the page, the UI elements may exceed the page scope and get truncated. In this case, you can enable the virtual container capability. When this capability is enabled, the logical pixel unit, horizontal breakpoints on the page, and window width are calculated based on half of the original size.

How to Develop

1. In the easy_go.json file, set enableReducedContainerSize to true to obtain the breakpoints after App Multiplier is enabled.

{
  "common": {
    "displayModeOptions": {
      ...
      "enableReducedContainerSize": true
    }
  }
}

FAQs

UI Elements Exceed the Page Scope and Get Truncated

Symptom

When App Multiplier is enabled and the split-view display is used, UI elements on the page exceed the page scope and get truncated, as shown in the following figure.

Possible Causes

When App Multiplier is enabled and the split-view display is used, two pages are displayed in one window at the same time. By default, each page occupies half of the window. If the window width is used for the element layout on the page, the UI elements may exceed the page scope and get truncated.

Solution

You are advised to take the following measures:

1. Preferentially use the adaptive layout capability of system components.
2. Enable the virtual container capability by setting enableReducedContainerSize to true in the App Multiplier configuration file. In this case, the logical pixel unit, horizontal breakpoints on the page, window width, and screen width are calculated based on half of the original size.
3. Use the API for obtaining the page size and imperceptible monitoring capabilities:

   on('navDestinationUpdate'): listens for status changes of the NavDestination component. In API version 23 and later, the returned status of the NavDestination component includes its size.

   on('routerPageUpdate'): listens for status changes of routerPage. In API version 23 and later, the returned information of routerPage includes its size.

   onRouterPageSizeChange: This callback function is triggered when the size of the visible router page changes.

   onNavDestinationSizeChange: This callback function is triggered when the size of the visible NavDestination changes.

In the component reuse scenario, the same resource is displayed only on one page.

Symptom

Invalid Page-level Window Policy

Symptom

In the App Multiplier scenario, when the preferredOrientation attribute provided by the NavDestination component is used to set the page orientation, the setting does not take effect.

Possible Causes

In the App Multiplier scenario, the left and right pages are displayed at the same time, and the orientations of the two pages must be the same.

Solution

You are advised to use the window-level solution and set the window policy through the setPreferredOrientation API provided by the Window component.

Sample Code

App Multiplier