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 functions such as opening a UI page or sending a message.

Basic concepts:

• Widget provider: an atomic service that controls what and how content is displayed in a widget and interacts with users.
• Widget host: an application that displays the widget content and controls the position where the widget is displayed in the host application.
• Widget Manager: 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 widget 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 callbacks in FormExtension.
• Create a FormBindingData instance.
• Update a widget through FormProvider.
• Develop the widget UI page.

Available APIs

The FormExtension class has the following APIs. For details, see FormExtension.

Table 1 FormExtension APIs

The FormExtension class also has a member context, that is, the FormExtensionContext class. For details, see FormExtensionContext.

Table 2 FormExtensionContext APIs

For details about the FormProvider APIs, see FormProvider.

Table 3 FormProvider APIs

How to Develop

Creating a FormExtension Instance

To create a widget in the stage model, implement the lifecycle callbacks 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 callbacks of FormExtension.

   export default class FormAbility extends FormExtension {
       onCreate(want) {
           console.log('FormAbility onCreate');
           // Persistently store widget information for subsequent use, such as during widget instance retrieval or 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, override this method for widget 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 the Widget Configuration File

• Configure Extension ability information under extensionAbilities in the module.json5 file. The internal field structure is described as follows:

For a Form Extension ability, you must specify metadata. Specifically, set name to ohos.extension.form (fixed), and set resource to the index of the widget configuration information.

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 configuration information. resource in metadata specifies the index of the widget configuration information. 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 configuration file.

  The internal field structure is described as follows:

 A configuration example is as follows:

 ```json

{ "forms": [{ "name": "widget", "description": "This is a 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" }] } ```

Persistently Storing Widget Data

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 the 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 data for subsequent use, such as widget instance retrieval and update.
           // The storeFormInfo API is not implemented here. For details about the implementation, see "Samples" below.
           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) {
           console.log('FormAbility onDestroy');

           // You need to implement the code for deleting the persistent widget data.
           // The deleteFormInfo API is not implemented here. For details about the implementation, see "Samples" below.
           deleteFormInfo(formId);
       }

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 it is deleted from the Widget Manager due to exceptions, such as crash of the widget framework, the widget provider will not be notified of which widget is deleted, and still keeps the data. In light of this, the widget provider should implement data clearing. If the widget host successfully converts a temporary widget into a normal one, the widget provider should also process the widget ID and store the data persistently. This prevents the widget provider from deleting the widget data when clearing temporary widgets.

Updating Widget Data

When a widget application initiates a data update upon a scheduled or periodic update, the application obtains the latest data and calls updateForm to update the widget. The sample code is as follows:

onUpdate(formId) {
    // To support scheduled update, periodic update, or update requested by the widget host, override this method for widget data update.
    console.log('FormAbility onUpdate');
    let obj = {
        "title": "titleOnUpdate",
        "detail": "detailOnUpdate"
    };
    let formData = formBindingData.createFormBindingData(obj);
    // Call the updateForm method to update the widget. Only the data passed through the input parameter is updated. Other information remains unchanged.
    formProvider.updateForm(formId, formData).catch((error) => {
        console.log('FormAbility updateForm, error:' + JSON.stringify(error));
    });
}

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.