Since API version 18, Form Kit provides the capability of displaying widgets on the lock screen to present critical information or shortcut operations. Users can access key information or use common features without unlocking the device. Lock screen widgets are typically used to show information such as weather and clocks, and support customization.
This section outlines how to use lock screen widgets, details their constraints, and provides development guidelines.
Information at fingertips: view application information on the lock screen without unlocking the device, driving application engagement and repeat visits.
One-tap access: instantly access application functionalities via shortcuts, enhancing operational efficiency.
You can add, delete, and rearrange widgets on the lock screen. Follow these steps:
Pinch the lock screen with two fingers to enter the editing mode. Four widget slots will appear. The lock screen supports only 1 x 1 and 1 x 2 widgets: a 1 x 1 widget occupies one slot, while a 1 x 2 widget requires two consecutive slots.
Tap any widget slot on the lock screen to access the widget management menu.
Choose a widget (such as Health or Clock) to add it to the lock screen.
In the editing mode, tap the minus sign in the upper-right corner of any widget to delete it.
Device: This feature is only supported on smartphones and tablets.
UI:
The lock screen supports only 1 x 1 and 1 x 2 widgets.
It is not recommended that lock screen widgets display sensitive user data. For details about the UI restrictions, see Widget Content Design.
Once a widget is created, configure it and integrate its open capabilities. The rest of the development process is consistent with that of regular widgets, and the specific steps are as follows.
Configure the renderingMode and supportDimensions fields in the form_config.json configuration file. The renderingMode field can only be set to singleColor or autoColor, and the value of the supportDimensions field must contain 1*1 or 1*2. For details, see Fields in Configuration File. The method of configuring the renderingMode field is changed in API version 18 and later versions.
// In API version 18 and later versions, the renderingMode field is configured as follows:
// entry/src/main/resources/base/profile/form_config.json
{
"forms": [
{
"name": "widget",
"displayName": "$string:widget_display_name",
"description": "$string:widget_desc",
"src": "./ets/widget/pages/WidgetCard.ets",
"uiSyntax": "arkts",
"isDynamic": true,
"isDefault": true,
"updateEnabled": false,
"scheduledUpdateTime": "10:30",
"renderingMode": "autoColor",
"updateDuration": 1,
"defaultDimension": "1*2",
"supportDimensions": [
"1*2",
"2*2"
]
}
]
} // In versions earlier than API version 18, the renderingMode field is configured as follows. The value 0 indicates autoColor, the value 1 indicates fullColor, and the value 2 indicates singleColor.
// entry/src/main/resources/base/profile/form_config.json
{
"forms": [
{
"name": "widget",
"displayName": "$string:widget_display_name",
"description": "$string:widget_desc",
"src": "./ets/widget/pages/WidgetCard.ets",
"uiSyntax": "arkts",
"isDynamic": true,
"isDefault": true,
"updateEnabled": false,
"scheduledUpdateTime": "10:30",
"updateDuration": 1,
"defaultDimension": "1*2",
"supportDimensions": [
"1*2",
"2*2"
],
"metadata": [
{
"name": "renderingMode",
"value": "2"
}
]
}
]
} To ensure data privacy and security, you need to request the open capability of lock screen widgets.
Therefore, when debugging or releasing an app, you must use sign manually and create a HarmonyOS app when requesting a profile. When creating an app, refer to the following guide to grant the app access to the open capability.
On the Open capability page, tap the request button corresponding to the lock screen widget.
In the New request window that is displayed, enter the request information and click Submit. Request reason: Mandatory. The value contains a maximum of 256 characters. Attachment: Optional. Only one attachment can be uploaded. The size cannot exceed 500 MB. An attachment can be a Word file, Excel file, image, video, or compressed package.
Return to the Open capability page. The original Request button changes to Requesting. You will receive the request result in one to three working days.
After the request is approved, the interaction center will send a notification to you, and Requesting will change to a dimmed Request button.
After the capability is approved, toggle on the widget switch and tap Save in the upper-right corner. Your application has successfully integrated the open capabilities.