Framework Specifications

File Organization

Directory Structure

The following figure illustrates a typical development directory structure of the JS module (entry/src/main/js/module) of a JS FA application.

Figure 1 Directory Structure

An image

The classification of files in the directory structure is as follows:

HTML template files with an extension of .html specify the layout of current pages.
CSS style files with an extension of .css specify page styles.
JS files with an extension of .js are used to process interactions between pages and users.

The purpose of each folder is as follows:

The app.js file is used for global JavaScript logic and application lifecycle management.
The pages folder is used to store all component pages.
The common folder is used to store common resource files, such as media resources and JS files.
The i18n folder is used to configure resources for scenes in different languages, such as text entries of applications and image paths.

WARNING

The i18n folder is reserved for developers. Renaming this folder is not allowed.

File Access Rules

Application resources can be accessed through absolute paths or relative paths. In this development framework, an absolute path starts with a “/” while a relative path starts with a “./” or “../”. The following describes the access rules:

To reference a code file, a relative path is required, for example, ../common/utils.js.
To reference a resource file, an absolute path is recommended, for example, /common/xxx.png.
The common folder is recommended to store common code files and resources files. which are accessed the previous rules to access these files.
In a CSS style file, the url() function is used to create the <url> data type, for example, url(/common/xxx.png).

When code file A needs to reference code file B:

Code file B can use either a relative path or an absolute path to reference a resource file if code file A and code file B are located in the same directory.
Code file B can only use an absolute path to reference a resource file if code file A and code file B are located in different directories. The reason is that the directory of code file B changes when Webpack bundles files.

Media File Formats

Table 1 Supported Image File Formats

Format	Supported Version	Supported File Format
BMP	API Version 3+	.bmp
JPEG	API Version 3+	.jpg
PNG	API Version 3+	.jpg

Storage Directory Definition

A specific scheme, which only supports internal, can be used to access some predefined file directories when an application uses a file storage API to access files. The actual directory locations vary with different devices. An access to files not in the following directory will be denied. The use of ../ is not allowed to access a parent directory.

The image component supports access to image resources in the private directories of an application. 5+

Directory Type	Path Prefix	Visibility to Access	Description
Private directories of an application	internal://app/	Only visible to this application	Removed with application uninstallation

js Tag Configuration

The js tag contains an instance name and the route information of pages.

Tag	Type	Default	Required	Description
name	string	default	Yes	Indicates the name of a JS instance.
pages	Array	-	Yes	Route information. For details, see “pages”.

The configuration of name and pages must be completed in the “js” tag of the configuration file.

pages

Defines the route information of each page. Each page contains a page path and a page name. The page name is the same as the page file name. For example:

{
        ...
        "pages": [
            "pages/index/index",
            "pages/detail/detail"
        ]
        ...
    }

Tip

The application homepage has a fixed path "pages/index/index".
No component name can be used as a file name, such as text.html and button.html.

Example

{
    "app": {
        "bundleName": "com.Xiaomi Watch.player",
        "version": {
            "code": 1,
            "name": "1.0"
        },
        "vendor": "example"
    }
    "module": {
        ...
        "js": [
            {
                "name": "default",
                "pages": [
                "pages/index/index",
                "pages/detail/detail"
                ]
            }
        ],
        "abilities": [
            {
                ...
            }
        ]
    }
}

app.js

The lifecycle implementation logic can be defined for each application in app.js, including:

onCreate: lifecycle function that is called when an application is created.
onDestory: lifecycle function that is called when an application is destroyed.

The following example only prints out the corresponding logs in the lifecycle functions:

// app.js
export default {
  onCreate() {
    console.info("Application onCreate");
  },
  onDestroy() {
    console.info("Application onDestroy");
  },
};

Multi-language Support

Applications based on the development framework usually target multiple countries and regions. Due to its multi-language capability, the development framework allows developers to develop a multi-language application version rather than multiple language editions. The multi-language application can switch between different languages. The multi-language support results in easy maintenance of projects.

Developers can use the multi-language capability of the development framework by defining and referencing resource files. To get the current language of the system in an application, see Getting Language.

Defining Resource Files

Resource files are used to store resource contents required for multi-language scenes. The development framework uses JSON files to store the definitions of resources.

A resource file is prepared for each language and region and placed in the i18n folder specified by the file organization. The file is named in the format of “language-region.json”. For example, the resource file for English (US) is named as en-US.json. If the development framework fails to find the resource file corresponding to the system language of an application, the resource contents in en-US.json are used by default.

The following shows the format of contents in a resource file:

en-US.json

{
  "strings": {
    "hello": "Hello world!",
    "object": "Object parameter substitution-{name}",
    "array": "Array type parameter substitution-{0}",
    "symbol": "@#$%^&*()_+-={}[]\\|:;\"'<>,./?"
  },

  "files": {
    "image": "image/en_picture.PNG"
  }
}

Referencing Resources

The $t method is used in applications for referencing resources. This method can be used in both HTML and JS files. The system displays the contents in the resource file of the corresponding language according to the current language environment and resource path. The resource path is specified by the path parameter in $t.
Table 1 $t Parameter Descriptions

Parameter	Type	Required	Description
path	string	Yes	Resource path
params	Array	No	Replaces the actual contents of placeholders during operation. Two types of placeholders are available: Named placeholder, such as {name}. An Object type is required to specify the actual content, for example, $t('strings.object', { name: 'Hello world' }). digit placeholder, such as {0}。 An Array type is required to specify the actual content, for example, $t('strings.array', ['Hello world']).

Code example

<!-- xxx.html -->
<div>
  <!-- Not use placeholder, text with "Hello world!" -->
  <text>{{ $t('strings.hello') }}</text>
  <!-- Named placeholder format, replace placeholder {name} with "Hello world" when it runs -->
  <text>{{ $t('strings.object', { name: 'Hello world' }) }}</text>
  <!-- Digit placeholder format, replace placeholder {0} with "Hello world" when it runs -->
  <text>{{ $t('strings.array', ['Hello world']) }}</text>
  <!-- First obtain resource contents in js, and "Hello world" is displayed in text -->
  <text>{{ hello }}</text>
  <!-- First obtain resource contents in js, and replace placeholder {name} with "Hello world". And then the text will display as 'Object parameter substitution-Hello world" -->
  <text>{{ replaceObject }}</text>
  <!-- First obtain resource contents in js, and replace placeholder {0} with "Hello world". And then the text will display as "Array type parameter substitution-Hello world" -->
  <text>{{ replaceArray }}</text>
  <!-- Path to obtain photos -->
  <image src="{{ $t('files.image') }}" class="image"></image>
  <!-- First obtain photo path in js, and then the photos will be displayed on image -->
  <image src="{{ replaceSrc }}" class="image"></image>
</div>

// xxx.js
// Following is the approach to js file.
export default {
  data: {
    hello: "",
    replaceObject: "",
    replaceArray: "",
    replaceSrc: "",
  },
  onInit() {
    this.hello = this.$t("strings.hello");
    this.replaceObject = this.$t("strings.object", { name: "Hello world" });
    this.replaceArray = this.$t("strings.array", ["Hello world"]);
    this.replaceSrc = this.$t("files.image");
  },
};

Syntax

Syntax Reference

HTML is a set of markup language used to build page contents based on components and events. It pages provides advanced capabilities such as data binding, event binding, form rendering, and condition rendering.

Page Structure

<!-- xxx.html -->
<div class="item-container">
  <text class="item-title">Image Show</text>
  <div class="item-content">
    <image src="/common/xxx.png" class="image"></image>
  </div>
</div>

Data Binding

<!-- xxx.html -->
<div onclick="changeText">
  <text> {{content[1]}} </text>
</div>

// xxx.js
export default {
  data: {
    content: ["Hello World!", "Welcome to my world!"],
  },
  changeText: function () {
    this.content.splice(1, 1, this.content[0]);
  },
};

Tip

Use the splice method to validate the change of data binding when data inside an array is modified.
JS expressions in HTML do not support ES6 syntax.

CSS Syntax Reference

Cascading Style Sheets (CSS) is a style language used to specify the HTML page structure. Each component has a default style. Various styles can be defined for components and pages in CSS style files.

Style Import

For the purpose of modular management and code reuse, CSS style files support the @import statement, which is used to import CSS files.

Style Declaration

The directory of each page contains a CSS file with the same name as the corresponding layout HTML file. This CSS file specifies the style of each component on the HTML page, which determines the display of components on the page.

Internal style. The style and class attributes can be used to control the style of a component. For example:

<!-- index.html -->
<div class="container">
  <text style="color: red">Hello World</text>
</div>

/* index.css */
.container {
  justify-content: center;
}

File import. An external style file can be imported to merge a predefined style. For example, define a style.css file in the common directory and then import this file in the first line in the index.css file.

/* style.css */
.title {
  font-size: 50px;
}

/* index.css */
@import "../../common/style.css";
.container {
  justify-content: center;
}

Selector

The CSS selector is used to select elements for which styles are to be added. The following table describes the supported selectors:

Selector	Example	Example Description
.class	.container	Selects all components with class="container".
#id	#titleId	Selects all components with id="titleId".
,	.title, .content	Selects all components with class="title" and class="content".

Example:

<!-- page layout xxx.html -->
<div id="containerId" class="container">
  <text id="titleId" class="title">title</text>
  <div class="content">
    <text id="contentId">content</text>
  </div>
</div>

/* page style xxx.css */
/* component style of class="title" */
.title {
  font-size: 30px;
}

/* component style of id="contentId" */
#contentId {
  font-size: 20px;
}

/* Set all padding of components in class="title" and class="content" as 5px */
.title,
.content {
  padding: 5px;
}

Pseudo-class

A CSS pseudo-class is a keyword in the selector that is used to specify a special state of the element to be selected.

Name	Supported Component	Description
:active	input[type="button"]	Indicates elements activated by a user, for example, a button pressed by a user. For lightweight smart wearables, the pseudo-class selector only supports the setting of background-color and background-image.
:checked	input[type="checkbox"、type="radio"]	Indicates elements whose checked attribute is true. For lightweight smart wearables, the pseudo-class selector only supports the setting of background-color and background-image.

The following is a pseudo-class example. This example sets the :active pseudo-class of buttons to control the style of pressed buttons.

<!-- index.html -->
<div class="container">
    <input type="button"class="button"value="Button"></input>
</div>

/* index.css */
.button:active {
  background-color: #888888; /*button is activated, background color changes into #888888 */
}

Style Precompiler

The precomplier provides programs that use specific syntax to generate CSS and functions such as variables and calculation. The precompiler provides more convenience for developers to define component styles. The precompiler supports the precompiling of Leaner CSS (LESS), Syntactically Awesome Stylesheets (SASS), and Sassy CSS (SCSS). Before using the style precompiler, you are required to change the suffix of the original CSS file to less, sass, or scss. For example, change the file name of index.css into index.less, index.sass, or index.scss.

Precomplie the current file. For example, change the original index.css file into index.less:

/* index.less */
/* Define parameter */
@colorBackground: #000000;
.container {
  background-color: @colorBackground; /* Use the parameter defined in the current less file */
}

Reference a precompiled file. For example, a style.scss file exists in the common directory. Change the original index.css file into index.scss and then reference style.scss:

/* style.scss */
/* Define parameter */
$colorBackground: #000000;

refer in index.scss:

/* index.scss */
/* import external scss file */
@import'../../common/style.scss';
.container{
    background-color: $colorBackground; /* use parameter defined in style.scss */
}

The common directory is recommended to store the precompiled files to be referenced.

JS Syntax Reference

A JS file is used to define the business logic of an HTML page. JS files support the ECMA JavaScript language. Due to its dynamic ability, JavaScript allows more flexibility in application design and makes applications more expressive. The following describes the supports for compiling and running a JS file.

Syntax

Supports ES6 syntax. Lightweight smart wearables only supports a few ES6 syntax, including:

let/const
arrow functions
class
default value
destructuring assignment
destructuring binding pattern
enhanced object initializer
for-of
rest parameter
template strings

Module declaration
Use the import method to reference a functional module:

import router from "@system.router";

Code reference
Use the import method to import JS codes:

import utils from "../../common/utils.js";

Object

Page object

Attribute	Type	Description
data	Object/Function	The data model of a page. The data type is object or function. If the data type is function, the return must be an object. An attribute name cannot start with $ or _. The reserved words for, if, show, or tid are not allowed.
$refs	Object	The object of a DOM element or a child component instance with its ref attribute registered.

Getting a DOM element

Use $refs to get a DOM element.

<!-- index.html -->
<div class="container">
  <image-animator
    class="image-player"
    ref="animator"
    images="{{images}}"
    duration="1s"
    onclick="handleClick"
  ></image-animator>
</div>

 // index.js
    export default {
    data: {
        images: [
        { src: '/common/frame1.png' },
        { src: '/common/frame2.png' },
        { src: '/common/frame3.png' },
        ],
    },
    handleClick() {
        const animator = this.$refs.animator; // obtain DOM element whose ref attribute is animator
        const state = animator.getState();
        if (state === 'paused') {
                animator.resume();
            } elseif (state === 'stopped') {
                animator.start();
            } else {
                animator.pause();
            }
        },
    };

Lifecycle API

Page lifecycle

Attribute	Type	Parameter	Return value	Description	Trigger Time
onInit	Function	None	None	Page initialization	Triggered upon completion of page initialization. Triggered only once.
onReady	Function	None	None	Page creation	Triggered upon completion of page creation. Triggered only once.
onShow	Function	None	None	Page display	Triggered upon display of the page.
onHide	Function	None	None	Page hide	Triggered when the page is hidden.
onDestroy	Function	None	None	Page destroy	Triggered when the page is destroyed.

The lifecycle API call sequence of page A:

Open page A: onInit() -> onReady() -> onShow()
Open page B on page A: onHide() -> onDestroy()
Return to page A from page B: onInit() -> onReady() -> onShow()
Exit page A: onHide() -> onDestroy()
Hide the pages in background: onHide()
Restore the pages in foreground: onShow()
Application lifecycle

Attribute	Type	Parameter	Return value	Description	Trigger Time
onCreate	Function	None	None	Application creation	Called upon creation of an application.
onDestroy	Function	None	None	Application exit	Triggered upon exit of an application.

# Framework Specifications

# File Organization

# Directory Structure

# File Access Rules

# Media File Formats

# Storage Directory Definition

# js Tag Configuration

# pages

# Example

# app.js

# Multi-language Support

# Defining Resource Files

# Referencing Resources

# Syntax

# Syntax Reference

# Page Structure

# Data Binding

# CSS Syntax Reference

# Style Import

# Style Declaration

# Selector

# Pseudo-class

# Style Precompiler

# JS Syntax Reference

# Syntax

# Object

# Getting a DOM element

# Lifecycle API

Framework Specifications

File Organization

Directory Structure

File Access Rules

Media File Formats

Storage Directory Definition

js Tag Configuration

pages

Example

app.js

Multi-language Support

Defining Resource Files

Referencing Resources

Syntax

Syntax Reference

Page Structure

Data Binding

CSS Syntax Reference

Style Import

Style Declaration

Selector

Pseudo-class

Style Precompiler

JS Syntax Reference

Syntax

Object

Getting a DOM element

Lifecycle API