Provides layout algorithms supported by the DynamicLayout component.
LayoutAlgorithm is the base type of layout algorithms for the dynamic layout container. It provides multiple layout algorithm implementations, including linear layout, stack layout, and grid layout. You can select an appropriate layout algorithm based on the actual scenario, or inherit CustomLayoutAlgorithm to implement a custom layout.
-
The initial APIs of this module are supported since API version 24. 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.
Modules to Import
import { LayoutAlgorithm, CustomLayoutAlgorithm, RowLayoutAlgorithm, ColumnLayoutAlgorithm, StackLayoutAlgorithm, GridLayoutAlgorithm } from '@kit.ArkUI'; LayoutAlgorithm
Basic layout algorithm of the DynamicLayout container.
This type of variable can be assigned a specific layout algorithm class object, such as an object of the CustomLayoutAlgorithm or RowLayoutAlgorithm class.
Model restriction: This API can be used only in the stage model.
Widget capability: This API can be used in ArkTS widgets since API version 24.
Atomic service API: This API can be used in atomic services since API version 24.
System capability: SystemCapability.ArkUI.ArkUI.Full
CustomLayoutAlgorithm
A custom layout algorithm class, which allows you to implement custom measurement and layout logic. It is suitable for complex layout scenarios that require fine-grained control over child component sizes and positions, such as waterfall flow layout, irregular grid layout, and dynamic flow layout. By overriding onMeasure and onLayout, you can implement layout strategies that are not covered by the built-in layout algorithms.
Decorator: @ObservedV2
The object of the CustomLayoutAlgorithm class can be used as the input parameter of the DynamicLayout component to specify a layout algorithm.
[h2]onMeasure
onMeasure(self: FrameNode, constraint: LayoutConstraint): void
Customizes the size of the child component to be measured. When the size of the dynamic layout component is determined, the ArkUI framework will transfer the FrameNode and layout constraint of the component to you through onMeasure. State variables should not be changed in this callback.
- onMeasure and onLayout usually need to be used together to complete the full custom layout process. The framework first calls onMeasure to measure the child component size, and then calls onLayout to set the child component position.
- In this API, you can call getChild() of FrameNode to obtain the child component FrameNode, call measure() of FrameNode to measure the child component size. For details, see Example 1: Implementing Waterfall Layout Using a Custom Layout Algorithm.
Model restriction: This API can be used only in the stage model.
Widget capability: This API can be used in ArkTS widgets since API version 24.
Atomic service API: This API can be used in atomic services since API version 24.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| self | FrameNode | Yes | Entity node of the dynamic layout component in the component tree, which is used to obtain the child component FrameNode and measure the child component size. |
| constraint | LayoutConstraint | Yes | Layout constraint used by the dynamic layout component for measurement. |
[h2]onLayout
onLayout(self: FrameNode, position: Position): void
Customizes the position of the child component to be arranged. When the position of the dynamic layout component is determined, the ArkUI framework will transfer the FrameNode and layout position of the component to you through onLayout. State variables should not be changed in this callback.
- onLayout and onMeasure usually need to be used together to complete the full custom layout process. The framework first calls onMeasure to measure the child component size, and then calls onLayout to set the child component position.
- In this API, you can call getChild() of FrameNode to obtain the child component FrameNode, call layout() of FrameNode to set the child component position. For details, see Example 1: Implementing Waterfall Layout Using a Custom Layout Algorithm.
Model restriction: This API can be used only in the stage model.
Widget capability: This API can be used in ArkTS widgets since API version 24.
Atomic service API: This API can be used in atomic services since API version 24.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| self | FrameNode | Yes | Entity node of the dynamic layout component in the component tree, which is used to obtain the child component FrameNode and set the child component position. |
| position | Position | Yes | Position information used in layout of the dynamic layout component. |
Example
For details, see Example 1: Implementing Waterfall Layout Using a Custom Layout Algorithm.
RowLayoutAlgorithm
A horizontal linear layout algorithm class, which is used to implement horizontal linear arrangement of child components. It is suitable for scenarios where child components need to be arranged horizontally, such as horizontal lists, toolbars, tab bars, and action button groups. It supports setting the spacing between child components, vertical alignment mode, horizontal alignment mode, and arrangement direction, which provides layout capabilities similar to the Row component.
Decorator: @ObservedV2
The object of the RowLayoutAlgorithm class can be used as the input parameter of the DynamicLayout component to specify a layout algorithm.
[h2]Attributes
Model restriction: This API can be used only in the stage model.
Widget capability: This API can be used in ArkTS widgets since API version 24.
Atomic service API: This API can be used in atomic services since API version 24.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| space | LengthMetrics | No | Yes | Horizontal spacing between child components in a horizontal layout. Value range: a non-negative number. Default value: LengthMetrics.vp(0) Invalid values are treated as the default value. Decorator: @Trace |
| alignItems | VerticalAlign | No | Yes | Vertical alignment mode of all child components. Default value: VerticalAlign.Center Invalid values are treated as the default value. Decorator: @Trace |
| justifyContent | FlexAlign | No | Yes | Horizontal alignment mode of all child components. Default value: FlexAlign.Start Invalid values are treated as the default value. Decorator: @Trace |
| isReverse | boolean | No | Yes | Whether to reverse the horizontal arrangement of child components. true indicates to reverse the horizontal arrangement of child components. The horizontal direction is affected by the common attribute direction. If the direction attribute takes effect, the child components are arranged based on direction and then are reversed based on isReverse. false indicates to arrange child components in the horizontal direction in normal order. Default value: false Invalid values are treated as the default value. Decorator: @Trace |
[h2]constructor
constructor(option?: RowLayoutAlgorithmOptions)
Constructs the horizontal linear layout algorithm class.
Model restriction: This API can be used only in the stage model.
Widget capability: This API can be used in ArkTS widgets since API version 24.
Atomic service API: This API can be used in atomic services since API version 24.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| option | RowLayoutAlgorithmOptions | No | Input parameters for constructing the horizontal linear layout algorithm, which are used to set the spacing, main axis alignment mode, cross axis alignment mode, and main axis arrangement direction of the layout algorithm. If not passed, the default value of each attribute is used. |
Example
For details, see Example 2: Switching the Layout Algorithm.
RowLayoutAlgorithmOptions
Sets the spacing, main axis alignment method, cross axis alignment method, and main axis arrangement direction of the horizontal linear layout algorithm.
Model restriction: This API can be used only in the stage model.
Widget capability: This API can be used in ArkTS widgets since API version 24.
Atomic service API: This API can be used in atomic services since API version 24.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| space | LengthMetrics | No | Yes | Horizontal spacing between child components in a horizontal layout. Value range: a non-negative number. Default value: LengthMetrics.vp(0) Invalid values are treated as the default value. |
| alignItems | VerticalAlign | No | Yes | Vertical alignment mode of all child components. Default value: VerticalAlign.Center Invalid values are treated as the default value. |
| justifyContent | FlexAlign | No | Yes | Horizontal alignment mode of all child components. Default value: FlexAlign.Start Invalid values are treated as the default value. |
| isReverse | boolean | No | Yes | Whether to reverse the horizontal arrangement of child components. true indicates to reverse the horizontal arrangement of child components. The horizontal direction is affected by the common attribute direction. If the direction attribute takes effect, the child components are arranged based on direction and then are reversed based on isReverse. false indicates to arrange child components in the horizontal direction in normal order. Default value: false Invalid values are treated as the default value. |
ColumnLayoutAlgorithm
A vertical linear layout algorithm class, which is used to implement vertical linear arrangement of child components. It is suitable for scenarios where child components need to be arranged vertically, such as vertical lists, vertically stacked form items, and vertical menus. It supports setting the spacing between child components, horizontal alignment mode, vertical alignment mode, and arrangement direction, which provides layout capabilities similar to the Column component.
Decorator: @ObservedV2
The object of the ColumnLayoutAlgorithm class can be used as the input parameter of the DynamicLayout component to specify a layout algorithm.
[h2]Attributes
Model restriction: This API can be used only in the stage model.
Widget capability: This API can be used in ArkTS widgets since API version 24.
Atomic service API: This API can be used in atomic services since API version 24.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| space | LengthMetrics | No | Yes | Vertical spacing between child components in a vertical layout. Value range: a non-negative number. Default value: LengthMetrics.vp(0) Invalid values are treated as the default value. Decorator: @Trace |
| alignItems | HorizontalAlign | No | Yes | Horizontal alignment mode of all child components. Default value: HorizontalAlign.Center Invalid values are treated as the default value. Decorator: @Trace |
| justifyContent | FlexAlign | No | Yes | Vertical alignment mode of all child components. Default value: FlexAlign.Start Invalid values are treated as the default value. Decorator: @Trace |
| isReverse | boolean | No | Yes | Whether to reverse the vertical arrangement of child components. true indicates to reverse the vertical arrangement of child components. The vertical direction is not affected by the common attribute direction. false indicates to arrange child components in the vertical direction in normal order. Default value: false Invalid values are treated as the default value. Decorator: @Trace |
[h2]constructor
constructor(option?: ColumnLayoutAlgorithmOptions)
Constructs the vertical linear layout algorithm class.
Model restriction: This API can be used only in the stage model.
Widget capability: This API can be used in ArkTS widgets since API version 24.
Atomic service API: This API can be used in atomic services since API version 24.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| option | ColumnLayoutAlgorithmOptions | No | Input parameters for constructing the vertical linear layout algorithm, which are used to set the spacing, main axis alignment method, cross axis alignment method, and main axis arrangement direction of the layout algorithm. If not passed, the default value of each attribute is used. |
Example
For details, see Example 2: Switching the Layout Algorithm.
ColumnLayoutAlgorithmOptions
Sets the spacing, main axis alignment method, cross axis alignment method, and main axis arrangement direction of the vertical linear layout algorithm.
Model restriction: This API can be used only in the stage model.
Widget capability: This API can be used in ArkTS widgets since API version 24.
Atomic service API: This API can be used in atomic services since API version 24.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| space | LengthMetrics | No | Yes | Vertical spacing between child components in a vertical layout. Value range: a non-negative number. Default value: LengthMetrics.vp(0) Invalid values are treated as the default value. |
| alignItems | HorizontalAlign | No | Yes | Horizontal alignment mode of all child components. Default value: HorizontalAlign.Center Invalid values are treated as the default value. |
| justifyContent | FlexAlign | No | Yes | Vertical alignment mode of all child components. Default value: FlexAlign.Start Invalid values are treated as the default value. |
| isReverse | boolean | No | Yes | Whether to reverse the vertical arrangement of child components. true indicates to reverse the vertical arrangement of child components. The vertical direction is not affected by the common attribute direction. false indicates to arrange child components in the vertical direction in normal order. Default value: false Invalid values are treated as the default value. |
StackLayoutAlgorithm
A stack layout algorithm class, which is used to implement stacked arrangement of child components. It is suitable for scenarios where child components need to be displayed in a stacking manner, such as stacked layers, floating buttons, content areas with backgrounds, and card stack effects. It supports setting the alignment mode of child components within the stack container, which provides layout capabilities similar to the Stack component.
Decorator: @ObservedV2
The object of the StackLayoutAlgorithm class can be used as the input parameter of the DynamicLayout component to specify a layout algorithm.
[h2]Attributes
Model restriction: This API can be used only in the stage model.
Widget capability: This API can be used in ArkTS widgets since API version 24.
Atomic service API: This API can be used in atomic services since API version 24.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| alignContent | LocalizedAlignment | No | Yes | Alignment mode of child components in the stack layout algorithm. Default value: LocalizedAlignment.CENTER Invalid values are treated as the default value. Decorator: @Trace |
[h2]constructor
constructor(option?: StackLayoutAlgorithmOptions)
Constructs the stack layout algorithm class.
Model restriction: This API can be used only in the stage model.
Widget capability: This API can be used in ArkTS widgets since API version 24.
Atomic service API: This API can be used in atomic services since API version 24.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| option | StackLayoutAlgorithmOptions | No | Input parameters for constructing the stack layout algorithm, which are used to set the nine-box grid alignment mode. If not passed, the default value of each attribute is used. |
Example
For details, see Example 2: Switching the Layout Algorithm.
StackLayoutAlgorithmOptions
Sets the alignment method of the stack layout algorithm.
Model restriction: This API can be used only in the stage model.
Widget capability: This API can be used in ArkTS widgets since API version 24.
Atomic service API: This API can be used in atomic services since API version 24.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| alignContent | LocalizedAlignment | No | Yes | Alignment mode of child components in the stack layout algorithm. Default value: LocalizedAlignment.CENTER Invalid values are treated as the default value. |
GridLayoutAlgorithm
A grid layout algorithm class, which is used to implement grid arrangement of child components. It is suitable for scenarios where child components need to be arranged in a grid format, such as grid menus, photo grids, application lists, and product displays. It supports setting the column count template, column spacing, and row spacing, which provides layout capabilities similar to the Grid component.
Decorator: @ObservedV2
The object of the GridLayoutAlgorithm class can be used as the input parameter of the DynamicLayout component to specify a layout algorithm.
[h2]Attributes
Model restriction: This API can be used only in the stage model.
Atomic service API: This API can be used in atomic services since API version 24.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| columnsTemplate | string | ItemFillPolicy | No | Yes | Column template of the current grid layout, defining the width and number of columns. The string type must conform to the template format, for example, '1fr' indicates a single-column layout, '1fr 1fr 1fr' indicates a three-column equal-width layout, and '1fr 2fr' indicates a two-column layout where the second column is twice as wide as the first. When ItemFillPolicy is used, adaptive column count can be implemented. Default value: '1fr' Invalid values are treated as the default value. Decorator: @Trace |
| columnsGap | LengthMetrics | No | Yes | Spacing between columns. Value range: a non-negative number. Default value: LengthMetrics.vp(0) Invalid values are treated as the default value. Decorator: @Trace |
| rowsGap | LengthMetrics | No | Yes | Spacing between rows. Value range: a non-negative number. Default value: LengthMetrics.vp(0) Invalid values are treated as the default value. Decorator: @Trace |
[h2]constructor
constructor(option?: GridLayoutAlgorithmOptions)
Constructs the grid layout algorithm class.
Model restriction: This API can be used only in the stage model.
Atomic service API: This API can be used in atomic services since API version 24.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| option | GridLayoutAlgorithmOptions | No | Input parameters for constructing the grid layout algorithm, which are used to set the number of columns, column spacing, and row spacing of the grid layout. If not passed, the default value of each attribute is used. |
Example
For details, see Example 2: Switching the Layout Algorithm.
GridLayoutAlgorithmOptions
Sets the number of columns, column spacing, and row spacing of the grid layout algorithm.
Model restriction: This API can be used only in the stage model.
Atomic service API: This API can be used in atomic services since API version 24.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| columnsTemplate | string | ItemFillPolicy | No | Yes | Column template of the current grid layout, defining the width and number of columns. The string type must conform to the template format, for example, '1fr' indicates a single-column layout, '1fr 1fr 1fr' indicates a three-column equal-width layout, and '1fr 2fr' indicates a two-column layout where the second column is twice as wide as the first. When ItemFillPolicy is used, adaptive column count can be achieved. Default value: '1fr' Invalid values are treated as the default value. |
| columnsGap | LengthMetrics | No | Yes | Spacing between columns. Value range: a non-negative number. Default value: LengthMetrics.vp(0) Invalid values are treated as the default value. |
| rowsGap | LengthMetrics | No | Yes | Spacing between rows. Value range: a non-negative number. Default value: LengthMetrics.vp(0) Invalid values are treated as the default value. |