JavaScript

You can use a .js file to define the service logic of an HML page. The JS UI framework supports the JavaScript language that conforms to the ECMAScript specification. With dynamic typing, JavaScript can make your application more expressive with a flexible design. The following describes the JavaScript compilation and running.

Syntax

The ES6 syntax is supported.

  • Module declaration

    Import functionality modules.

    import router from '@system.router';
    
  • Code reference

    Import JavaScript code.

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

Object

  • Application object

    Attribute

    Type

    Description

    $def

    Object

    Object that is exposed in the app.js file and obtained by this.$app.$def.

    NOTE:

    Application objects do not support data binding. Data update should be triggered on the UI.

    Example Code

    // app.js
    export default {
      onCreate() {
        console.info('AceApplication onCreate');
      },
      onDestroy() {
        console.info('AceApplication onDestroy');
      },
      globalData: {
        appData: 'appData',
        appVersion: '2.0',
      },
      globalMethod () {
        console.info('This is a global method!');
        this.globalData.appVersion = '3.0';
      }
    };
    
    // index.js
    export default {
      data: {
        appData: 'localData',
        appVersion:'1.0',
      },
      onInit() {
        this.appData = this.$app.$def.globalData.appData;
        this.appVersion = this.$app.$def.globalData.appVersion;
      },
      invokeGlobalMethod() {
        this.$app.$def.globalMethod();
      },
      getAppVersion() {
        this.appVersion = this.$app.$def.globalData.appVersion;
      }
    }
    
  • Page objects

    Attribute

    Type

    Description

    data

    Object/Function

    Data model of the page. If the attribute is of the function type, the return value must be of the object type. The attribute name cannot start with a dollar sign ($) or underscore (_). Do not use reserved words (for, if, show, and tid).

    Do not use this attribute and private or public at the same time.

    $refs

    Object

    DOM elements or child component instances that have registered the ref attribute. For example code, see Obtaining a DOM element.

    private

    Object

    Data model of the page. Private data attribute can be modified only on the current page.

    public

    Object

    Data model of the page. Behaviors of public data attributes are the same as those of the data attribute.

    props

    Array/Object

    Used for communication between components. This attribute can be transferred to components via <tag xxxx='value'>. A props name must be in lowercase and cannot start with a dollar sign ($) or underscore (_). Do not use reserved words (for, if, show, and tid). Currently, props does not support functions. For details, see Custom Components.

    computed

    Object

    Used for pre-processing an object for reading and setting. The result is cached. The name cannot start with a dollar sign ($) or underscore (_). Do not use reserved words. For details, see Custom Components.

Function

  • Data functions

    Attribute

    Type

    Parameter

    Description

    $set

    Function

    key: string

    value: any

    Adds an attribute or modifies an existing attribute.

    Usage:

    this.$set('key',value): Add an attribute.

    $delete

    Function

    key: string

    Deletes an attribute.

    Usage:

    this.$delete('key'): Delete an attribute.

    Example Code

    export default {
      data: {
        keyMap: {
          OS: 'OpenHarmony',
          Version: '2.0',
        },
      },
      getAppVersion() {
        this.$set('keyMap.Version', '3.0');
        console.info("keyMap.Version = " + this.keyMap.Version); // keyMap.Version = 3.0
    
        this.$delete('keyMap');
        console.info("keyMap.Version = " + this.keyMap); // log print: keyMap.Version = undefined
      }
    }
    
  • Public functions

    Attribute

    Type

    Parameter

    Description

    $element

    Function

    id: string Component ID

    Obtains the component with a specified ID. If no ID is specified, the root component is returned. For example code, see Obtaining a DOM element.

    Usage:

    <div id='xxx'></div>

    • this.$element('xxx'): Obtain the component whose ID is xxx.
    • this.$element(): Obtain the root component.

    $root

    Function

    N/A

    Obtains the root ViewModel instance. For example code, see Obtaining the ViewModel.

    $parent

    Function

    N/A

    Obtains the parent ViewModel instance. For example code, see Obtaining the ViewModel.

    $child

    Function

    id: string Component ID

    Obtains the ViewModel instance of a custom child component with a specified ID. For example code, see Obtaining the ViewModel.

    Usage:

    this.$child('xxx'): Obtain the ViewModel instance of a custom child component whose ID is xxx.

  • Event function

    Attribute

    Type

    Parameter

    Description

    $watch

    Function

    data: string

    callback: function name. The callback has two parameters. The first one is the new attribute value, and the second is the original value.

    Listens for attribute changes. If the value of the data attribute changes, the bound event is triggered. For details, see Custom Components.

    Usage:

    this.$watch('key', callback)

Obtaining a DOM element

  1. Use $refs to obtain a DOM element.

    <!-- index.hml -->
    <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 the DOM element whose $refs attribute is animator.
        const state = animator.getState();
        if (state === 'paused') {
          animator.resume();
        } else if (state === 'stopped') {
          animator.start();
        } else {
          animator.pause();
        }
      },
    };
    
  2. Call $element to obtain a DOM element.

    <!-- index.hml -->
    <div class="container">
      <image-animator class="image-player" id="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.$element('animator'); // Obtain the DOM element whose ID is animator.
        const state = animator.getState();
        if (state === 'paused') {
          animator.resume();
        } else if (state === 'stopped') {
          animator.start();
        } else {
          animator.pause();
        }
      },
    };
    

Obtaining the ViewModel

The following shows files of the root page:

<!-- root.hml -->
<element name='parentComp' src='../../common/component/parent/parent.hml'></element>
<div class="container">
  <div class="container">
    <text>{{text}}</text>
    <parentComp></parentComp>
  </div>
</div>
// root.js
export default {
  data: {
    text: 'I am a root!',
  },
}

Customize the parent component.

<!-- parent.hml -->
<element name='childComp' src='../child/child.hml'></element>
<div class="item" onclick="textClicked">
  <text class="text-style" onclick="parentClicked">Click this parent component</text>
  <text class="text-style" if="{{show}}">Hello parent component!</text>
  <childComp id = "selfDefineChild"></childComp>
</div>
// parent.js
export default {
  data: {
    show: false,
    text: 'I am the parent component!',
  },
  parentClicked () {
    this.show = !this.show;
    console.info('parent component get parent text');
    console.info(`${this.$parent().text}`);
    console.info("The parent component gets the child function.");
    console.info(`${this.$child('selfDefineChild').childClicked()}`);
  },
}

Customize the child component.

<!-- child.hml -->
<div class="item" onclick="textClicked">
  <text class="text-style" onclick="childClicked">Child component clicked</text>
  <text class="text-style" if="{{show}}">Hello child component</text>
</div>
// child.js
export default {
  data: {
    show: false,
    text: 'I am the child component!',
  },
  childClicked () {
    this.show = !this.show;
    console.info('child component get parent text');
    console.info('${this.$parent().text}');
    console.info('child component get root text');
    console.info('${this.$root().text}');
  },
}

Lifecycle Functions

  • Page lifecycle

    Attribute

    Type

    Parameter

    Return Value

    Description

    Called When

    onInit

    Function

    None

    None

    Listens for page initialization.

    Page initialization is complete. This function is called only once in a lifecycle.

    onReady

    Function

    None

    None

    Listens for page creation.

    A page is created. This function is called only once in a lifecycle.

    onShow

    Function

    None

    None

    Listens for page display.

    The page is displayed.

    onHide

    Function

    None

    None

    Listens for page disappearance.

    The page disappears.

    onDestroy

    Function

    None

    None

    Listens for page destruction.

    The page is destroyed.

    onBackPress

    Function

    None

    Boolean

    Listens for the back button action.

    The back button is tapped.

    • true means that the page processes the return logic.
    • false means that the default return logic is used.
    • If no value is returned, the default return logic is used.

    onActive()5+

    Function

    None

    None

    Listens for age activation.

    The page is activated.

    onInactive()5+

    Function

    None

    None

    Listens for page suspension.

    The page is suspended.

    onNewRequest()5+

    Function

    None

    None

    Listens for a new FA request.

    The FA has been started and a new request is received.

    The lifecycle functions of page A are called in the following sequence:

    • Open page A: onInit() -> onReady() -> onShow() -> onActive()
    • Open page B on page A: onInactive() -> onHide()
    • Go back to page A from page B: onShow() -> onActive()
    • Exit page A: onBackPress() -> onInactive() -> onHide() -> onDestroy()
    • Hide page A: onInactive() -> onHide()
    • Show background page A on the foreground: onShow()
  • Application lifecycle

    Attribute

    Type

    Parameter

    Return Value

    Description

    Called When

    onCreate

    Function

    None

    None

    Listens for application creation.

    The application is created.

    onDestroy

    Function

    None

    None

    Listens for application exit.

    The application exits.