LiveViewCardExtensionAbility is an ExtensionAbility component for the custom extension area of live view widgets. It is designed for real-time activity scenarios that require rich custom content in the extension area. By inheriting from this class and implementing the app's extension component, you can present customized content in the live view extension area.
Since: 26.0.0
LiveViewCardExtensionAbility runs in an independent subprocess and cannot start other abilities across processes.
Network access is not allowed.
The execution time for this ExtensionAbility is strictly limited to within 80 milliseconds each time. Timeout will cause the custom extension area of the live view to fail to display properly. Therefore, complex or time-consuming processing is prohibited.
To ensure system security and stability and prevent LiveViewCardExtensionAbility from abusing system resources, the system restricts its capabilities. Referencing certain modules is not supported. For details, please refer to the Appendix.
import { LiveViewCardExtensionAbility } from '@kit.LiveViewKit'; Device behavior differences: This module is supported on phones and tablets, but does not respond on other device types.
Model restriction: This attribute can be used only in the stage model.
System capability: SystemCapability.LiveView.LiveViewService
Device behavior differences: This API is supported on phones and tablets, but does not respond on other device types.
Since: 26.0.0
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| context | LiveViewCardExtensionContext | No | No | Context of LiveViewCardExtensionAbility, which inherits from ExtensionContext. |
onRender(param: Record<string, string>): CardInfo
Callback triggered by the system when an instance of the component that you implement by inheriting from the LiveViewCardExtensionAbility is loaded. Within onRender, you can implement the service logic and UI component rendering for the widget extension area of a live view widget, and return CardInfo to be loaded to the system for page rendering.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.LiveView.LiveViewService
Device behavior differences: This API is supported on phones and tablets, but does not respond on other device types.
Since: 26.0.0
Parameters:
| Name | Type | Mandatory | Description |
|---|---|---|---|
| param | Record<string, string> | Yes | CustomLayout.abilityParameters passed in when you create a custom extension area for a live view widget. By default, it contains the following keys (their values are assigned by the system; manual modifications will not take effect): ohos.extra.param.key.colorMode: dark or light mode of the live view widget (dark: dark mode; light: light mode) ohos.extra.param.key.fontColor: font color of the live view widget (the value is in #ARGB format, with a number sign (#) and 8 hexadecimal digits) ohos.extra.param.key.contentWidth: width of the live view widget, in vp. (The distance between the left and right borders of the custom extension area and the live view widget borders is 12 vp each; that is, custom extension area width = live view widget width - 12 × 2). |
Returns:
| Type | Description |
|---|---|
| CardInfo | Widget rendering information object. |
Widget rendering information object returned by the onRender API.
Model restriction: This attribute can be used only in the stage model.
System capability: SystemCapability.LiveView.LiveViewService
Device behavior differences: This API is supported on phones and tablets, but does not respond on other device types.
Since: 26.0.0
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| pagePath | string | No | No | Path of the extension area page to be loaded into the system. The system will render the page. |
| storage | LocalStorage | No | Yes | Page-level UI state storage unit, which is used to pass the state attribute of the content specified by pagePath. |
import { LiveViewCardExtensionAbility } from '@kit.LiveViewKit';
import { CardInfo } from '@hms.core.liveview.LiveViewCardExtensionAbility';
import { hilog } from '@kit.PerformanceAnalysisKit';
export default class LiveViewCardExtAbility extends LiveViewCardExtensionAbility {
onRender(param: Record<string, string>): CardInfo {
hilog.info(0x0000, 'LiveViewCardTag', 'LiveViewCardExtAbility onRender begin.');
// Construct the parameters from param into LocalStorage to pass them to the page for usage.
const storage = new LocalStorage(param);
// Load the custom extension area page of the live view widget.
return {
pagePath: 'pages/LiveViewCardPage',
storage: storage
}
}
} @Entry({ useSharedStorage: true })
@Component
struct LiveViewCardPage {
private storage: LocalStorage | undefined = this.getUIContext().getSharedLocalStorage();
// Obtain the parameters passed in AbilityParameters.
private words: string | undefined = this.storage?.get('words');
// Parse and obtain the width, light/dark mode, and font color of the custom extension area of the live view widget.
private contentWidth: string | undefined = this.storage?.get('ohos.extra.param.key.contentWidth');
private colorMode: string | undefined = this.storage?.get('ohos.extra.param.key.colorMode');
private fontColor: string | undefined = this.storage?.get('ohos.extra.param.key.fontColor');
getFontColor(): string {
// You can customize the font color based on the light/dark mode or use the default font color.
let color = this.fontColor as string; // Default font color. If the default font color is used, delete the following colorMode-based check logic.
// Customize the font color based on the value of colorMode.
if (this.colorMode == 'dark') {
// In dark mode, you can customize the font color based on service requirements. In the following example, the font color is red.
color = '#FFFF3300';
} else if (this.colorMode == 'light') {
// In light mode, you can customize the font color based on your service requirements. In the following example, the font color is green.
color = '#FF33CC66';
}
return color;
}
build() {
Column() {
Scroll() {
Column() {
Text(this.words)
.fontColor(this.getFontColor())
}
.width(this.contentWidth)
}
}
}
} The following table lists the APIs that LiveViewCardExtensionAbility is not allowed to call.