Cross-Process Application Capability Extension (UIExtension, for System Applications Only)

UIExtension allows you to embed UI extensions from one application into another, providing a seamless experience as users interact with different application functionalities within a single application UI.

Basic Concepts

• UIExtensionComponent component

  Defined and used in the host application, UIExtensionComponent is provided by ArkUI for use in the application following the ArkTS declarative paradigm.

• UIExtensionAbility component

Defined and used in the provider application, UIExtensionAbility allows the provider to run in a separate process and creates UI extensions that can be embedded in the host application’s window.

Working Principle

UIExtension offers a capability for cross-process application sharing. It is embedded into the host application (system application) process in the form of a component using the UIExtensionComponent. When the host application starts, it triggers the Application Management Service (AMS) to start the provider application process. AMS is mainly responsible for the management tasks of application startup, exit, and switching.

After implementation, the page of the provider application can be displayed in the host application as a component:

After being started by AMS, the provider application can exchange data with the host application.

• The host application sends messages to the provider application through UIExtensionProxy.send, and the provider can obtain the messages using UIExtensionContentSession.setReceiveDataCallback.
• The provider application sends messages to the host application through UIExtensionContentSession.sendData, and the host can receive the messages using UIExtensionProxy.onReceive.

Available Capabilities

Basic Component Capabilities

• Component-based UIExtensionComponent: provides an embedded extension capability that allows the embedding and invocation of page extensions from other applications within the application page.
• Full-screen UIExtension: presents content in a full-screen modal for immersive interaction, without being obscured by other elements. System applications can expose specific components or Node-APIs based on the underlying capabilities of UIExtension, enabling third-party applications to utilize these for creating full-screen modal experiences.

Available Capabilities of the UIExtensionAbility Process

UIExtension is designed to facilitate the sharing of capabilities across different applications, offering a high degree of flexibility. It operates by launching the provider application’s capabilities through a cross-process approach for use by the current (host) application. This mechanism involves service interactions between two separate processes, which is fundamentally different from the interactions between common components and their host applications.

Below is a detailed list of the attributes, events, components, Node-APIs, and other features that the provider application can utilize within UIExtensionAbility.

As component capabilities are subject to frequent updates, the current list of unsupported and partially supported features only reflects the status at the time of this document. Whether new capabilities are supported can be determined by referring to the principles of capability support. For capabilities that are currently unsupported, you can submit an issue to request support to the relevant component and UIExtension teams, which will then analyze the feasibility and provide support accordingly.

Universal Attributes

Due to the complexities of the cross-process communication mechanism, the UIExtension component is not able to influence other components or the host application’s information, such as the application context UIContext and application window information.

In scenarios where component attributes involve cross-component interactions, the following capabilities are not supported:

• The attributes of the provider component cannot control, assign, or merge with the attributes of other components or host application components. For example, the component ID is not supported.
• The attributes of the provider component cannot control display effects or animations that extend beyond the boundaries of the UIExtension component. For example, the modal transition is not supported.

The details are as follows.

Components

By default, the provider application cannot interact with the host application’s components or process context. Specifically, the following are not supported:

• Effects that exceed a component’s boundaries, such as the Navigation component displaying into the safe area
• Components that rely on other components or require cross-component or cross-application control and access, for example, PluginComponent for accessing other components or FormComponent for displaying pages from other applications across processes
• Components that depend on the host application’s window information or process UIContext instance for capabilities, interactions, or animations, such as the FolderStack component

The details are as follows.

Node-API

The capabilities provided by Node-APIs in the UIExtension scenario must account for their potential to extend beyond the current component and interact with the host application’s components and process context. Specifically, the following are not supported.

• The API may require information from the host application’s context or window, such as UIContext.
• The API may control or influence not just the component itself but also other components or aspects of the host application, such as UI appearance.

The details are as follows.

Constraints

Security Capability Constraints

The UIExtensionComponent (on the host side) can access applications that have integrated the UIExtensionAbility (on the provider side), offering a universal capability for application sharing. As UIExtension capabilities do not independently include a security mechanism, the provider application must utilize other ArkUI capabilities to protect against potential attacks from the host application, including scenarios with CreateModalUIExtension.

Considering the extensive capabilities of UIExtension (including those derived from UIExtension, such as those for CreateModalUIExtension in the system), if there are security concerns within the provider application that cannot be resolved within UIExtension, alternative approaches should be considered. Using UIExtension without proper security measures poses potential risks to both the provider and host applications.

Usage modes:

• CreateModalUIExtension (full-screen modal mode): CreateModalUIExtension is an inner class interface used exclusively by system applications to launch cross-process UIs through the development of Node-APIs or components. In this mode, a modal that overlays the application is created, preventing any components or windows from the host application from obscuring the UIExtension, and resizing of the component is not permitted.

• UIExtensionComponent (component mode): This mode is exclusively for system applications and can be used within applications through the ArkTS declarative paradigm. Integrated as a component, UIExtensionComponent allows for interaction effects similar to those of other components within the application.

In component mode, to avoid being obscured by the host application’s subwindows:

• The provider application can determine, based on its service needs, whether to allow the host application to obscure the UI.

• A recommended measure to prevent obscuration is the use of the hideNonSecureWindows API.

• This approach has a drawback: Once applied, it restricts the host application’s interaction capabilities, as it can no longer create subwindows that could cover the provider application’s window.

Nesting Constraints

UIExtension capabilities allow for a nested dependency chain as the following: application A (UIAbility) -> application B (UIExtensionAbility) -> application C (UIExtensionAbility). However, because of the cross-process nature, too many nesting levels can lead to a sharp decline in application interaction performance. Therefore, the following constraints are imposed:

• No more than three levels of nesting: Excessive nesting levels can lead to frequent cross-process interactions, degrading response performance and resulting in a poor user experience.
• No circular nesting allowed: Circular nesting, such as application A (UIAbility) -> application B (UIExtensionAbility) -> application C (UIExtensionAbility) -> back to application B (UIExtensionAbility), can cause application B to become unresponsive in synchronous processing scenarios, leading to potential deadlocks.

Event Processing Mechanism Constraints

Events are handled synchronously or asynchronously based on their use case:

• Interactions between the host process and the provider process are handled asynchronously by default: This avoids performance issues and deadlocks, which could affect the overall interaction experience.
• Synchronous event handling principles: Synchronous events are supported where they have a low trigger frequency and minimal performance impact; they should meet the actual use scenarios.

When using the UIExtension capabilities, comply with the following design constraints:

• Synchronous event handling scenarios: Performance issues due to deep nesting or functional issues due to circular nesting cannot be resolved by the UIExtension component mechanism. You need to analyze and resolve these issues based on their service scenarios, such as reducing nesting levels or using non-UIExtension component solutions.
• Asynchronous event handling scenarios: Both the UIExtension component and the host application’s components may receive events simultaneously. You need to manage this based on the use scenario. For example, you can configure the host application components not to handle the events. If this is not feasible, you are advised to replace the UIExtension component to ensure a seamless interaction experience.

Page Rendering Experience Constraints

As UIExtension involves cross-process application calls, the processing between the host application process and the provider application process cannot be synchronized, leading to different experience issues compared to regular components. Be aware of the performance constraints of rendering pages across multiple processes with this component and take targeted measures.

• Flickering white screen: Initiating a new process through UIExtension to deliver functionality involves a sequence of steps – creation, launch, and page rendering – that require time to complete. During this period, users may notice a brief display of the UIExtensionComponent’s default white background, resulting in a flickering white screen.
• Desynchronization between rendering and display: When the host application page changes rapidly (such as during screen rotation or window resizing), there can be a desynchronization between the rendering of the host application page and the content displayed within the UIExtension component. This issue arises from cross-process interactions; while the provider application’s process tasks are triggered by the host application, layout tasks are handled in the respective process’s JavaScript thread. There is no guarantee of synchronization between the host application’s and provider application’s rendering tasks, resulting in desynchronization.

When developing the provider application, consider the following design constraints:

• Use scenarios with minimal layout changes.
• When layout changes occur, the provider application’s JavaScript thread should execute as few tasks as possible to ensure that it can respond to layout change tasks promptly.

You can mitigate the flickering white screen issue with the provider application in the following ways:

• Adjust the background color of the UIExtensionComponent (for instructions, see Background) to match the background color of the host application’s and provider application’s pages, to deliver a seamless transition and prevent noticeable changes during the loading process.
• Utilize the placeholder mechanism provided by this component to configure a custom UI, which will be displayed before the provider application page is fully displayed.

If the mitigation does not fully meet the application’s interaction requirements due to the constraints of cross-process capabilities, it is recommended that you consider alternative solutions.

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkUI

harmony 鸿蒙Atomic Service Full Screen Launch Component (FullScreenLaunchComponent)

harmony 鸿蒙Arc Button (ArcButton)

harmony 鸿蒙Animation Smoothing

harmony 鸿蒙Animation Overview

harmony 鸿蒙Frame Animation (ohos.animator)

harmony 鸿蒙Implementing Property Animation

harmony 鸿蒙Property Animation Overview

harmony 鸿蒙Dialog Box Overview

harmony 鸿蒙Blur Effect