This content originally appeared on DEV Community and was authored by 程序员一鸣
Foreword
this article is based on Api13
in the previous article, we simply understood the relevant knowledge of service cards, so in this article, we will implement a service card from 0 to 1.
Create Card
creating cards is very simple. You can right-click any file under your main module in Application or meta-Service, select New->Service Widget, and select whether you want to implement static or dynamic cards. Here, you don’t have to struggle, because after the creation is completed, we can modify the card type through the isDynamic parameter in the form_config.json configuration file. If it is empty or true, it is a dynamic card, false is a static card, so it doesn’t matter which one you choose here.
At present, five templates are provided statically and four are provided dynamically. You can choose one of them according to actual business needs.
After selecting a template, you will enter the following page, that is, the configuration page of the Service card, from top to bottom: Service widget name: the name of the Service card; Display name, the name displayed by the card; description: description information of the card; Language: development Language, ArkTs is recommended here; supportDimensions: the appearance rules supported by the card, 1*2: indicates one row and two columns, and so on; Ability name: card lifecycle management file.
After the configuration is completed, click Finish at the bottom, and we will complete a default service card, which can be run directly. After running, after long pressing the desktop icon, the card options will be displayed:
After clicking on the card, the default card UI will be displayed. We can click to add it to the desktop:
this will display the service card we just created on the desktop:
card Directory Structure
after creation, the following files will be generated in our original project. First, the entryformability file under the EntryFormAbility package is a card extension module, which mainly provides life cycle callbacks such as card creation, destruction and refresh. WidgetCard under pages of widget package is mainly based on ArkUI to provide card UI development capability. Form_conget.jdson under resources is mainly used for configuration information.
Introduction of main documents
the configuration of a card is mainly through three files, namely the EntryFormAbility file, WidgetCard file and form_config.json configuration file in the above directory structure. Let’s analyze them one by one:
EntryFormAbility file
it is mainly a card extension module that provides lifecycle callbacks such as card creation, destruction, and refresh. It is inherited from FormExtensionAbility. The source code is as follows:
export default class EntryFormAbility extends FormExtensionAbility {
onAddForm(want: Want) {
// Called to return a FormBindingData object.
const formData = '';
return formBindingData.createFormBindingData(formData);
}
onCastToNormalForm(formId: string) {
// Called when the form provider is notified that a temporary form is successfully
// converted to a normal form.
}
onUpdateForm(formId: string) {
// Called to notify the form provider to update a specified form.
}
onFormEvent(formId: string, message: string) {
// Called when a specified message event defined by the form provider is triggered.
}
onRemoveForm(formId: string) {
// Called to notify the form provider that a specified form has been destroyed.
}
onAcquireFormState(want: Want) {
// Called to return a {@link FormState} object.
return formInfo.FormState.READY;
}
}
onAddForm: the interface used by the card provider to receive notifications about creating cards. formBindingData. The FormBindingData object is the data to be displayed by the card; onCastToNormalForm: the notification interface for the card provider to receive temporary cards to normal cards; onUpdateForm: the notification interface for the card provider to receive updated cards with parameters, and call the formProvider’s updateForm interface to refresh card data after obtaining the latest data; onFormEvent: the notification interface for the card provider to receive and process card events; onRemoveForm: the interface for the card provider to receive and query card status notifications returns the initial card status by default (this method can be selectively rewritten).
WidgetCard file
it is mainly a card UI view, where cards can be drawn. It supports some components, events, dynamic effects, data management, and state management capabilities of the declarative paradigm. When using it, you can check whether the official Api is marked with the “card capability” mark. If so, it is proved that it can be used in ArkTS cards.
form_config.json configuration file
the form_config configuration file is the information filled in the service card configuration, as shown below:
{
"forms": [
{
"name": "widget",
"displayName": "$string:widget_display_name",
"description": "$string:widget_desc",
"src": "./ets/widget/pages/WidgetCard.ets",
"uiSyntax": "arkts",
"window": {
"designWidth": 720,
"autoDesignWidth": true
},
"colorMode": "auto",
"isDynamic": true,
"isDefault": true,
"updateEnabled": false,
"scheduledUpdateTime": "10:30",
"updateDuration": 1,
"defaultDimension": "2*2",
"supportDimensions": [
"2*2"
]
}
]
}
the fields are summarized below:
related Summary
there are many optional attributes in the form_config configuration file. The above table is not comprehensive. When you write, you must check the official documents.
This article label: HarmonyOS/service card, reference: service card guidance for official documents.
This content originally appeared on DEV Community and was authored by 程序员一鸣