harmony 鸿蒙Customization Capability Overview

2025-06-12
浏览 (6)

Customization Capability Overview

Customization Capability Levels

Customization capabilities in the ArkUI development framework allow for flexible UI development and personalization. These capabilities span various control levels, each suited for different use cases. Lower levels of customization provide closer access to foundational capabilities, offering greater flexibility but also higher development complexity and demands on developer skills.

Currently, the following customization levels are available, organized from the most basic to the most advanced: - Custom composition: the most basic customization method provided by the ArkUI framework, which combines and reuses existing components through the basic capabilities of built-in and custom components to encapsulate new components. This includes basic capabilities such as encapsulation, layout, drawing, and animation. - Custom extension: a range of modifiers, including the following, that enable the enhancement and customization of UI components in a way that is separate from the UI: AttributeModifier, GestureModifier, DrawModifier. - Custom nodes: node objects with some basic capabilities of underlying entity nodes, which can be mixed and displayed with built-in components through custom placeholder nodes. There are three types of custom nodes: FrameNode, RenderNode, and BuilderNode. These nodes have customization capabilities for individual nodes, such as measurement and layout, setting basic attributes, setting event listeners, and custom drawing and content rendering. - Custom rendering: custom content rendering implemented by writing display data generated by EGL/OpenGLES or other decoded media stream data into the NativeWindow object, thanks to the “surface” mode of XComponent that exposes the NativeWindow object and the NDK APIs.

A Quick Glance of Customization Capabilities

Different levels of customization capabilities serve various use cases. The table below gives a brief explanation of each capability, its use cases, and best practices for implementation.

|Customization Level|Customization Capability|Description and Use Case| |–|–|–| |Custom composition|Custom encapsulation|Use @Component for basic component encapsulation by combining existing components into new custom ones.
Use @Builder for lightweight UI encapsulation and reuse, abstracting repetitive UI structures into a Builder method called within the component’s build method.| |Custom composition|Custom layout|Use the stack layout with size and position settings for custom arrangement of child components, useful in scenarios with clearly defined child components and relatively simple layout needs.
Use custom component layout lifecycle callbacks for adjusting child component positions, ideal for encapsulating specific layout algorithms.| |Custom composition|Custom drawing|Use Canvas for custom drawing integrated into custom components, with APIs similar to W3C Canvas, suitable for developers familiar with web development and for porting W3C-based Canvas drawing libraries in non-performance-critical scenarios.
Use shape components (including Rect, Path, Circle, Ellipse, Polyline, and Polygon) to create custom graphics similar to SVG vector graphics, which is suitable for simple graphic combinations and interactive graphic animations.| |Custom composition|Custom animation|Use property animation for custom animation effects on animatable component properties.
Use @AnimatableExtend to animate non-animatable properties.
Use APIs in @ohos.animator to create custom animations similar to frame animations, by modifying properties frame-by-frame or integrating with custom drawing.| |Custom extension|Attribute extension|Use AttributeModifier for UI and style separation, dynamic setting and updating of attributes and events, and exporting and reusing across files, which is useful for component encapsulation and extending properties through exposed modifiers.
Use custom modifiers for simplified attribute passing and extension in component encapsulation.
Use AttributeUpdater for direct attribute setting to improve performance in scenarios with frequent attribute updates.| |Custom extension|Gesture extension|Use GestureModifier for gesture extension, adding or removing gestures dynamically, with cross-file export and reuse, which is suitable for encapsulating and reusing custom gesture handling logic.| |Custom extension|Content extension|Use DrawModifier to extend or replace default component drawing with custom content.
Use ContentModifier to replace component content with custom Builder methods in components with clear content and interaction areas.| |Custom nodes|Component node|Use FrameNode for the following capabilities:
Fully custom node capability, including custom measurement, layout, and rendering, with support for dynamically adding and removing nodes, setting universal attributes, and configuring event callbacks. It is suitable for third-party frameworks with high-level languages that do not have their own rendering engines but rely on system capabilities for layout, events, animation, and rendering.
Native component proxy capabilities for built-in components, enabling traversal of the node tree. By using FrameNodes within the component tree, you can navigate the entire tree and access component information or register additional event listeners. This is useful for combining seamless listening APIs to implement services such as tracking, advertising SDKs, and mid-end DFX.
Use TypedFrameNode for creating specific types of FrameNodes, which can then be mounted with APIs of FrameNode to generate a custom component tree. It is ideal for seamless integration with dynamic frameworks developed in high-level programming languages.| |Custom nodes|Rendering node|Use RenderNode for lightweight rendering nodes that provide rendering-related attribute setting, custom drawing, and node operation capabilities. It is suitable for integration with third-party frameworks without a rendering engine but relying on system animation and rendering capabilities.| |Custom nodes|Mixing with built-in components|Use BuilderNode to create and update built-in components and component trees. It allows for the integration of declarative components within custom FrameNode or RenderNode structures, facilitating the hybrid display of built-in components with custom nodes. It also allows builder content to be exported as textures, facilitating same-layer rendering in environments created by the XComponent.| |Custom rendering|Independent rendering|Use XComponent’s surface mode with the NDK APIs to create a standalone rendering environment through NativeWindow, which enables writing display data generated by EGL/OpenGLES or other media stream data decoded through various methods into the NativeWindow object. This way, custom rendering is achieved without relying on other components provided by the ArkUI framework. It is suitable for frameworks that come with their own rendering engines, such as those used in gaming engines, mapping applications, and camera software.|