How to Build Dynamic Widgets in HarmonyOS Next: A Step-by-Step Guide

Read the original article：How to Build Dynamic Widgets in HarmonyOS Next: A Step-by-Step Guide

Introduction

In this article, we will look at how to develop a dynamic widget step by step, moving through an already created HarmonyOS project. I’ll keep the basics simple, from installation to configuration, lifecycle to event management.

How to add widgets

First, we need to determine which module to add our widget to. I will use the entry module in this example.

➕ Widget Creation Steps:

Right-click the entry module.

From the menu, follow the steps: New -> Service Widget -> Dynamic Widget.

When you complete this process, a new folder called widget should be created under your entry module.

You should have a WidgetCard.ets file under Pages where you can do things about your widget.

A form_config.json file will also be automatically added under the resources folder.
Also, your EntryFormAbility file was created automatically

🖼️ What is the WidgetCard.ets?

Where we define the visual interface of our widget is the WidgetCard component. This component is marked with @Component annotation and is used to configure content to be displayed on the widget.

The following is a sample WidgetCard component:

@Entry
@Component
struct WidgetCard {
  readonly title: string = 'Hello World';
  readonly actionType: string = 'router';
  readonly abilityName: string = 'EntryAbility';
  readonly message: string = 'add detail';
  readonly fullWidthPercent: string = '100%';
  readonly fullHeightPercent: string = '100%';

  build() {
    Row() {
      Column() {
        Text(this.title)
          .fontSize($r('app.float.font_size'))
          .fontWeight(FontWeight.Medium)
          .fontColor($r('sys.color.font_primary'))
      }
      .width(this.fullWidthPercent)
    }
    .height(this.fullHeightPercent)
    .onClick(() => {
      postCardAction(this, {
        action: this.actionType,
        abilityName: this.abilityName,
        params: {
          message: this.message
        }
      });
    })
  }
}

This component displays the text “Hello World” in full screen and when clicked triggers a redirect with the message “add detail" via EntryAbility

⚙️ What is form_config.json?

This file contains the configuration settings for your widget. For example:

{
  "isDynamic": true,
  "isDefault": true,
  "updateEnabled": false,
  "scheduledUpdateTime": "10:30",
  "updateDuration": 1,
  "defaultDimension": "2*2",
  "supportDimensions": [
    "2*2"
  ]
}

Through this configuration, you can customize settings such as the widget’s sizes, dimensions and update frequency.

🧠What is EntryFormAbility?

The EntryFormAbility class is automatically created to manage widget-related lifecycle events. Basically, here are the following methods:
🔹 onAddForm(want: Want)
Called when a new form is added. Creates and returns form data:

public onAddForm(want: Want) {
  const formData = want.abilityName ?? '';
  return formBindingData.createFormBindingData(formData);
}

🔹 onUpdateForm(formId: string)
This is the function that is called when you need to update the form:

public onUpdateForm(formId: string) {
  hilog.info(domain, formId, 'onUpdateForm');
}

🔹 onFormEvent(formId: string, message: string)
Works when special events such as user interactions are triggered on the widget:

public onFormEvent(formId: string, message: string) {
  hilog.info(domain, formId + '-' + message, 'onFormEvent');
}

🚀 Conclusion

Although the process of widget development on HarmonyOS may seem complicated at first, with the right steps, it can turn into a very pleasant experience. In this article, I only touched on beginner dynamic widget setup. In future articles, I will cover advanced topics such as data transmission, scheduled updates, and user interactions.