Screen adaptation

Introduction

In Zepp OS 3.x, we have introduced a new screen adaptation solution, which abstracts the screen features into square, round, and bracelet-like screens.

With the screen feature configuration in the app.json file, and coding according to the screen adaptation specification, organizing layout files and resource files, your small program can run on devices with corresponding screen shapes without adapting to specific devices.

info

This screen specification only applies to Small Program Configuration App.json V3 and above.

UI Design Benchmark

For small programs that need to be adapted to the screen, developers need to design based on the benchmark.

There are currently the following design benchmarks:

1. Round screen benchmark: 480 x 480
2. Square screen benchmark: 390 x 450
3. Bracelet-like screen benchmark: 194 x 368

Screen adaptation specification

The adaptation specification includes three parts:

• Configuration of app.json in small program configuration
• Layout file
• Resource file, mainly including image resources

Configuration of app.json in small program configuration

In the small program configuration app.json file of the V3 version, a separate build target target is added.

The platforms of this target contains an array of screen feature configurations.

In this process, we specify which screen type devices the small program needs to support, and the screen feature configuration array needs to maintain several sets of corresponding js layout files.

Take an example:

{
  "platforms": [
    {
      "st": "r"
    },
    {
      "st": "s"
    },
    {
      "st": "b"
    },
    {
      "st": "r",
      "sr": "w466"
    }
  ]
}

st stands for Screen Type, which represents the screen type.

st Value	Description
r	Round screen
s	Square screen
b	Bracelet-like screen

sr stands for Screen Resolution and its format is w<width>, where width represents the screen width, such as w480.

Going back to the example, this screen feature configuration array represents that the small program supports 4 sets of layout schemes and corresponds to four independent js layout files. Next, we will introduce the layout file.

Layout file specification

Each screen feature configuration in app.json target requires an independent layout file corresponding to it, the file naming rule is [name].[config-qualifier].layout.js, and the file naming suffix is agreed as layout.js.

Symbol	Description
name	File name
config-qualifier	Configuration qualifier

info

Naming rules for configuration qualifiers config-qualifier:

The value of sr is in front, followed by the value of st. If st and sr are configured at the same time, use - to separate them.

The example in the previous text assumes that the file name of the page is index.js.

Configuration	Config-qualifier Value	Layout File Name	Description
{st: "r"}	r	index.r.layout.js	This layout file applies to round screen devices.
{st: "s"}	s	index.s.layout.js	This layout file applies to square screen devices.
{st: "b"}	b	index.b.layout.js	This layout file applies to bracelet-like screen devices.
{st: "r", sr: "w466"}	w466-r	index.w466-r.layout.js	This layout file applies to round screen devices with a screen width of 466 px.

In index.js, it is agreed to use such an import statement.

// index.js
import { layout } from 'zosLoader:./[name].[pf].layout.js'

This statement will automatically import the corresponding layout file based on the screen characteristics of the model during the build process.

tip

When writing layout-related code, use the px function under the @zos/utils module to handle all coordinate-related properties.

tip

The layout file directory corresponding to the page file is consistent with the directory where the page file is stored.

Resource file specification

Each screen feature corresponds to a set of layout files and also corresponds to an independent resource file directory.

Taking the index.js file as an example, the layout file of this page needs to be modified by the configuration modifier config-qualifier, and at the same time, the resource file directory also uses the config-qualifier modifier.

Look at an example directly, assuming that the value of the target field in app.json is common.

• Page Logic
  • index.js
• Layout File
  • index.r.layout.js
    • Corresponding resource file directory assets/common.r
  • index.s.layout.js
    • Corresponding resource file directory name assets/common.s
  • index.b.layout.js
    • Corresponding resource file directory name assets/common.b
  • index.w466-r.layout.js
    • Corresponding resource file directory name assets/common.w466-r

Complete example

For the complete example, please refer to 3.0-preview calories of the preview version of Small Program calories 3.0-preview calories.