Stage Widget Development

Widget Overview

A widget is a set of UI components used to display important information or operations for an application. It provides users with direct access to a desired application service, without requiring them to open the application.

A widget displays brief information about an application on the UI of another application (host application, currently system applications only) and provides basic interactive features such as opening a UI page or sending a message. The widget host is responsible for displaying the service widget.

Basic concepts:

• Widget provider

  The widget provider is an atomic service that provides the content to be displayed. It controls the display content, component layout, and component click events of a widget.

• Widget host

  The widget host is an application that displays the widget content and controls the position where the widget is displayed in the host application.

• Widget Manager

  The Widget Manager is a resident agent that manages widgets added to the system and provides functions such as periodic widget update.

NOTE

The widget host and provider do not keep running all the time. The Widget Manager starts the widget provider to obtain widget information when a widget is added, deleted, or updated.

You only need to develop widget content as the widget provider. The system automatically handles the work done by the widget host and Widget Manager.

The widget provider controls the widget content to display, component layout, and click events bound to components.

When to Use

Stage ability development refers to the development conducted by the widget provider based on the stage model. As a widget provider, you need to carry out the following operations:

• Develop the lifecycle callback functions in FormExtension.
• Create a FormBindingData object.
• Update a widget through FormProvider.
• Develop the widget UI page.

Available APIs

The FormExtension class has the context attribute. For details on the APIs provided by the FormExtension class, see FormExtension.

Table 1 FormExtension APIs

The context attribute of the FormExtension class inherits from the FormExtensionContext class. For details about the APIs provided by the FormExtensionContext class, see FormExtensionContext.

Table 2 FormExtensionContext APIs

For details about the FormProvider APIs, see FormProvider.

Table 3 FormProvider APIs

How to Develop

Creating a Form Extension

To create a widget in the stage model, you need to implement the lifecycle callback functions of FormExtension. The sample code is as follows:

1. Import the required modules.

   import FormExtension from '@ohos.application.FormExtension'
   import formBindingData from '@ohos.application.formBindingData'
   import formInfo from '@ohos.application.formInfo'
   import formProvider from '@ohos.application.formProvider'
   

2. Implement the lifecycle callback functions of FormExtension.

   export default class FormAbility extends FormExtension {
       onCreate(want) {
           console.log('FormAbility onCreate');
           // Persistently store widget information for subsequent use, such as widget instance retrieval and update.
           let obj = {
               "title": "titleOnCreate",
               "detail": "detailOnCreate"
           };
           let formData = formBindingData.createFormBindingData(obj);
           return formData;
       }
       onCastToNormal(formId) {
           // Called when the widget host converts the temporary widget into a normal one. The widget provider should do something to respond to the conversion.
           console.log('FormAbility onCastToNormal');
       }
       onUpdate(formId) {
           // To support scheduled update, periodic update, or update requested by the widget host for a widget, override this method for data update.
           console.log('FormAbility onUpdate');
           let obj = {
               "title": "titleOnUpdate",
               "detail": "detailOnUpdate"
           };
           let formData = formBindingData.createFormBindingData(obj);
           formProvider.updateForm(formId, formData).catch((error) => {
               console.log('FormAbility updateForm, error:' + JSON.stringify(error));
           });
       }
       onVisibilityChange(newStatus) {
           // Called when the widget host initiates an event about visibility changes. The widget provider should do something to respond to the notification.
           console.log('FormAbility onVisibilityChange');
       }
       onEvent(formId, message) {
           // If the widget supports event triggering, override this method and implement the trigger.
           console.log('FormAbility onEvent');
       }
       onDestroy(formId) {
           // Delete widget data.
           console.log('FormAbility onDestroy');
       }
       onConfigurationUpdated(config) {
           console.log('FormAbility onConfigurationUpdated, config:' + JSON.stringify(config));
       }
   }
   

Configuring config.json for the Form Ability

Configure the module.json file for the Form ability.

• The internal field structure of the extensionAbility module is described as follows:

For a Form Extension ability, set type to form and metadata to the widget details.

A configuration example is as follows:

 ```json

"extensionAbilities": [{ "name": "FormAbility", "srcEntrance": "./ets/FormAbility/FormAbility.ts", "label": "$string:form_FormAbility_label", "description": "$string:form_FormAbility_desc", "type": "form", "metadata": [{ "name": "ohos.extension.form", "resource": "$profile:form_config" }] }] ```

• Configure the widget profile module. In the metadata of the Form Extension ability, the resource file path specified by ohos.extension.form must be used. For example, $profile:form_config means that form_config.json in the resources/base/profile/ directory of the development view is used as the widget profile.

  The internal field structure is described as follows:

 A configuration example is as follows:

 ```json

{ "forms": [{ "name": "widget", "description": "This is a service widget.", "src": "./js/widget/pages/index/index", "window": { "autoDesignWidth": true, "designWidth": 720 }, "isDefault": true, "colorMode": "auto", "supportDimensions": ["22"], "defaultDimension": "22", "updateEnabled": true, "scheduledUpdateTime": "10:30", "updateDuration": 1, "formConfigAbility": "ability://ohos.samples.FormApplication.MainAbility" }] } ```

Widget Data Persistence

Mostly, the widget provider is started only when it needs to obtain information about a widget. The Widget Manager supports multi-instance management and uses the widget ID to identify an instance. If the widget provider supports widget data modification, it must persistently store the data based on the widget ID, so that it can access the data of the target widget when obtaining, updating, or starting a widget.

       onCreate(want) {
           console.log('FormAbility onCreate');

           let formId = want.parameters["ohos.extra.param.key.form_identity"];
           let formName = want.parameters["ohos.extra.param.key.form_name"];
           let tempFlag = want.parameters["ohos.extra.param.key.form_temporary"];
           // Persistently store widget information for subsequent use, such as widget instance retrieval and update.
           storeFormInfo(formId, formName, tempFlag, want);

           let obj = {
               "title": "titleOnCreate",
               "detail": "detailOnCreate"
           };
           let formData = formBindingData.createFormBindingData(obj);
           return formData;
       }

You should override onDestroy to delete widget data.

       onDestroy(formId) {
           // Delete widget data.
           deleteFormInfo(formId);
           console.log('FormAbility onDestroy');
       }

For details about the persistence method, see Lightweight Data Store Development.

Note that the Want passed by the widget host to the widget provider contains a temporary flag, indicating whether the requested widget is a temporary one.

• Normal widget: a widget that will be persistently used by the widget host

• Temporary widget: a widget that is temporarily used by the widget host

Data of a temporary widget is not persistently stored. If the widget framework is killed and restarted, data of a temporary widget will be deleted. However, the widget provider is not notified of which widget is deleted, and still keeps the data. Therefore, the widget provider should implement data clearing. In addition, the widget host may convert a temporary widget into a normal one. If the conversion is successful, the widget provider should process the widget ID and store the data persistently. This prevents the widget provider from deleting persistent data when clearing temporary widgets.

Developing the Widget UI Page

You can use HML, CSS, and JSON to develop the UI page for a JavaScript-programmed widget.

NOTE

Currently, only the JavaScript-based web-like development paradigm can be used to develop the widget UI.

• hml:

<div class="container">
    <stack>
        <div class="container-img">
            <image src="/common/widget.png" class="bg-img"></image>
        </div>
        <div class="container-inner">
            <text class="title">{{title}}</text>
            <text class="detail_text" onclick="routerEvent">{{detail}}</text>
        </div>
    </stack>
</div>

• css:

.container {
 flex-direction: column;
 justify-content: center;
 align-items: center;
}

.bg-img {
 flex-shrink: 0;
 height: 100%;
}

.container-inner {
 flex-direction: column;
 justify-content: flex-end;
 align-items: flex-start;
 height: 100%;
 width: 100%;
 padding: 12px;
}

.title {
 font-size: 19px;
 font-weight: bold;
 color: white;
 text-overflow: ellipsis;
 max-lines: 1;
}

.detail_text {
 font-size: 16px;
 color: white;
 opacity: 0.66;
 text-overflow: ellipsis;
 max-lines: 1;
 margin-top: 6px;
}

• json:

{
  "data": {
    "title": "TitleDefault",
    "detail": "TextDefault"
  },
  "actions": {
    "routerEvent": {
      "action": "router",
      "abilityName": "com.example.MyApplication.hmservice.FormAbility",
      "params": {
        "message": "add detail"
      }
    }
  }
}

Now you've got a widget shown below.

Development Example

The following sample is provided to help you better understand how to develop a widget on the stage model:

FormExtAbility

This sample provides a widget. Users can create, update, and delete widgets on the home screen of their devices or by using their own widget host. This sample also implements widget information persistence by using lightweight data storage.