The DistributedExtensionAbility module provides the base class for extension capabilities in multi-device collaboration scenarios (for example, dedicated communication services between wearables and mobile phones).
As the base class for extending capabilities in multi-device collaboration scenarios, this module provides the following capabilities:
-
Lifecycle management: provides lifecycle callbacks onCreate, onCollaborate, and onDestroy, covering the complete lifecycle of a collaborative ExtensionAbility from creation to destruction. This allows your app to execute service logic such as initialization, collaborative decision-making, and resource cleanup at different stages.
-
Collaborative decision-making: provides the onCollaborate callback to help an app determine whether to accept (ACCEPT/REJECT) a collaboration request based on the collaboration parameters transmitted by the caller during cross-device startup. This allows the app to flexibly control whether to continue the collaboration process.
-
Context: provides the distributedExtensionContext, which allows you to connect to and disconnect from a remote ServiceExtensionAbility to implement cross-device service calling and data exchange.
The following figure shows the core class structure of the collaboration extension and its relationship with the context and custom subclass.
As shown in the preceding figure:
- Inheritance relationship:** DistributedExtensionContext** inherits from ExtensionContext, and the custom subclass is inherited from DistributedExtensionAbility.
- Composition relationship: DistributedExtensionAbility has the context attribute of the DistributedExtensionContext type and provides collaboration capabilities such as connecting to and disconnecting from the remote ServiceExtensionAbility.
You can obtain the capabilities for multi-device collaboration by inheriting DistributedExtensionAbility and implementing the onCreate, onCollaborate, and onDestroy lifecycle callbacks.
The initial APIs of this module are supported since API version 20. Newly added APIs will be marked with a superscript to indicate their earliest API version.
The APIs of this module can be used only in the stage model.
[h2]Attributes
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.DistributedSched.AppCollaboration
Device behavior differences: If this API is called on a wearable device that does not support distributed services, it does not work.
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| context | DistributedExtensionContext | No | No | Context of the DistributedExtension. This context inherits from ExtensionContext. |
[h2]onCreate
onCreate(want: Want): void
Callback invoked to initialize the service logic when a DistributedExtensionAbility instance is created.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.DistributedSched.AppCollaboration
Device behavior differences: If this API is called on a wearable device that does not support distributed services, it does not work.
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| want | Want | Yes | Want information related to the current extension, which is used to carry the initialization configuration required for creating the extension. |
Example
import { Want } from '@kit.AbilityKit';
import { DistributedExtensionAbility } from '@kit.DistributedServiceKit';
export default class DistributedExtension extends DistributedExtensionAbility {
onCreate(want: Want) {
console.info(`DistributedExtension Create ok`);
console.info(`DistributedExtension on Create want: ${JSON.stringify(want)}`);
console.info(`DistributedExtension Create end`);
}
} [h2]onCollaborate
onCollaborate(wantParam: Record<string, Object>): AbilityConstant.CollaborateResult
Defines an extension lifecycle callback, which is invoked to return the collaboration result in multi-device collaboration scenarios. The returned result determines whether to continue the collaboration process.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.DistributedSched.AppCollaboration
Device behavior differences: If this API is called on a wearable device that does not support distributed services, it does not work.
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| wantParam | Record<string, Object> | Yes | Collaboration callback parameter, which is a key-value pair object carrying collaboration-related data transmitted by the caller. You can obtain these data through key values such as ohos.extra.param.key.supportCollaborateIndex and CollaborationValues to determine whether to accept the collaboration request and process the collaboration logic, which affects whether the collaboration process continues. |
Return value
| Type | Description |
|---|---|
| AbilityConstant.CollaborateResult | Whether the coordinator app accepts the collaboration result. The value ACCEPT indicates that the collaboration is accepted and the collaboration process continues. The value REJECT indicates that the collaboration is rejected and the collaboration process ends. |
Example
import { abilityConnectionManager, DistributedExtensionAbility } from '@kit.DistributedServiceKit';
import { AbilityConstant } from '@kit.AbilityKit';
export default class DistributedExtension extends DistributedExtensionAbility {
onCollaborate(wantParam: Record<string, Object>) {
console.info(`DistributedExtension onCollabRequest Accept to the result of Ability collaborate`);
let sessionId = -1;
const collaborationValues = wantParam["CollaborationValues"] as abilityConnectionManager.CollaborationValues;
if (!collaborationValues) {
console.error('Failed to get collaborationValues.');
return sessionId;
}
console.info(`onCollab, collaborationValues: ${JSON.stringify(collaborationValues)}`);
return AbilityConstant.CollaborateResult.ACCEPT;
}
} [h2]onDestroy
onDestroy(): void
Callback invoked to clear resources when a ServiceExtensionAbility instance is destroyed.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.DistributedSched.AppCollaboration
Device behavior differences: If this API is called on a wearable device that does not support distributed services, it does not work.
Example
import { DistributedExtensionAbility } from '@kit.DistributedServiceKit';
export default class DistributedExtension extends DistributedExtensionAbility {
onDestroy() {
console.info('DistributedExtension onDestroy ok');
}
} Appendix
DistributedExtensionAbility does not support referencing the following modules.