目录

GridItem

The GridItem component provides a single item in a grid.

  • This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
  • This component can be used only as a child of Grid.
  • When this component is used with LazyForEach, its child components are created when it is created. When this component is used with if/else or ForEach, or when the parent component is Grid, its child components are created when it is laid out.
  • If a Grid component contains a large number of GridItem components, using columnStart/columnEnd or rowStart/rowEnd to set the size of GridItem components can lead to performance issues, especially when scrollToIndex is used to scroll to a specific index. This is because Grid will traverse all GridItem nodes sequentially to find the specified index, which can be time-consuming. To address this issue, it is recommended that you use GridLayoutOptions for layout, which significantly improves the efficiency of finding the position of GridItem components. For best practices, see Optimizing Frame Loss for Grid Component Loading.

Child Components

This component can contain a single child component.

APIs

GridItem(value?: GridItemOptions)

Creates a GridItem component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value11+ GridItemOptions No Parameters of the grid item, containing the style parameter of the GridItemStyle enum type.

Attributes

[h2]rowStart

rowStart(value: number)

Sets the start row number of the component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value number Yes

Start row number of the component.

In scenarios where you need to specify the start row and column numbers and the number of rows and columns of a GridItem, you are advised to use the GridLayoutOptions parameter of the Grid component. For details, see Example 1: Creating a Fixed Row and Column Grid Layout and Example 3: Implementing a Scrollable Grid with Grid Items Spanning Rows and Columns.

Value range: [0, Total number of rows – 1].

[h2]rowEnd

rowEnd(value: number)

Sets the end row number of the component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value number Yes

End row number of the component.

In scenarios where you need to specify the start row and column numbers and the number of rows and columns of a GridItem, you are advised to use the GridLayoutOptions parameter of the Grid component. For details, see Example 1: Creating a Fixed Row and Column Grid Layout and Example 3: Implementing a Scrollable Grid with Grid Items Spanning Rows and Columns.

Value range: [0, Total number of rows – 1].

[h2]columnStart

columnStart(value: number)

Sets the start column number of the component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value number Yes

Start column number of the component.

In scenarios where you need to specify the start row and column numbers and the number of rows and columns of a GridItem, you are advised to use the GridLayoutOptions parameter of the Grid component. For details, see Example 1: Creating a Fixed Row and Column Grid Layout and Example 3: Implementing a Scrollable Grid with Grid Items Spanning Rows and Columns.

Value range: [0, Total number of columns – 1].

[h2]columnEnd

columnEnd(value: number)

Sets the end column number of the component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value number Yes

End column number of the component.

In scenarios where you need to specify the start row and column numbers and the number of rows and columns of a GridItem, you are advised to use the GridLayoutOptions parameter of the Grid component. For details, see Example 1: Creating a Fixed Row and Column Grid Layout and Example 3: Implementing a Scrollable Grid with Grid Items Spanning Rows and Columns.

Value range: [0, Total number of columns – 1].

In scenarios where you need to specify the start row and column numbers and the number of rows and columns of a GridItem, you are advised to use the GridLayoutOptions parameter of the Grid component. For details, see Example 1: Creating a Fixed Row and Column Grid Layout and Example 3: Implementing a Scrollable Grid with Grid Items Spanning Rows and Columns.

Rules for setting rowStart, rowEnd, columnStart, and columnEnd:

The following table describes the rules for handling abnormal values for GridItem row and column numbers.

Attribute Setting Exception Type Layout Principles After Correction
Only columnsTemplate is set Any row or column exception Laid out in a row-by-row then column-by-column manner
Only rowsTemplate is set Any row or column exception Laid out in a row-by-row then column-by-column manner
Both rowsTemplate and columnsTemplate are set rowStart < rowEnd Row span = min(rowEnd - rowStart + 1, total number of rows)
Both rowsTemplate and columnsTemplate are set rowStart > rowEnd Laid out in a row-by-row then column-by-column manner
Both rowsTemplate and columnsTemplate are set columnStart < columnEnd Column span = min(columnEnd - columnStart + 1, total number of columns)
Both rowsTemplate and columnsTemplate are set columnStart > columnEnd Laid out in a row-by-row then column-by-column manner

[h2]forceRebuild(deprecated)

forceRebuild(value: boolean)

Whether to re-create the component when it is being built.

This API is supported since API version 7 and deprecated since API version 9. Whether to re-create the component is automatically determined based on the component attributes and child component changes. No manual configuration is required.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value boolean Yes

Sets whether to re-create the component when it is being built.

Default value: false.

[h2]selectable8+

selectable(value: boolean)

Sets whether the grid item is selectable in the mouse selection box area. This attribute takes effect only when mouse box selection is enabled for the parent Grid container.

This attribute must be used before the polymorphic style is set. Otherwise, the style settings will not take effect.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value boolean Yes

Whether the grid item is selectable in the mouse selection box area. The value means that the grid item is selectable in the mouse selection box area, and false means the opposite.

Default value: true.

[h2]selected10+

selected(value: boolean)

Sets whether the grid item is selected. This attribute supports two-way binding through $$.

This attribute must be used before the polymorphic style is set. Otherwise, the style settings will not take effect.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value boolean Yes

Whether the grid item is selected. The value means that the grid item is selected, and false means that the grid item is in the default state.

Default value: false.

GridItemOptions11+

Defines the style of a grid item.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Read-Only Optional Description
style GridItemStyle No Yes

Style of the grid item.

Default value: GridItemStyle.NONE.

If this parameter is set to GridItemStyle.NONE, no style is applied.

If this parameter is set to GridItemStyle.PLAIN, the grid item is in hover or press style depending on the state.

GridItemStyle11+

Enumerates styles of grid items.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Value Description
NONE 0 No style.
PLAIN 1 Hover or press style.

To set the focused style for the grid item, the grid container must have paddings of greater than 4 vp for accommodating the focus frame of the grid item.

Events

[h2]onSelect8+

onSelect(event: (isSelected: boolean) => void)

Triggered when the selected state of the grid item changes.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
isSelected boolean Yes Returns true if the grid item is selected in the mouse selection box area; returns false otherwise.

Example

[h2]Example 1: Setting the Grid Item Position

This example shows how to set the grid item position using ColumnStart, ColumnEnd, RowStart, and RowEnd. In scenarios where you need to specify the start row and column numbers and the number of rows and columns of a GridItem, you are advised to use the GridLayoutOptions parameter of the Grid component. For details, see Example 1: Creating a Fixed Row and Column Grid Layout and Example 3: Implementing a Scrollable Grid with Grid Items Spanning Rows and Columns.

// xxx.ets
@Entry
@Component
struct GridItemExample {
  @State numbers: string[] = ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12', '13', '14', '15'];

  build() {
    Column() {
      Grid() {
        GridItem() {
          Text('4')
            .fontSize(16)
            .backgroundColor(0xFAEEE0)
            .width('100%')
            .height('100%')
            .textAlign(TextAlign.Center)
        }.rowStart(1).rowEnd(2).columnStart(1).columnEnd(2) // Set valid row and column numbers.

        ForEach(this.numbers, (item: string) => {
          GridItem() {
            Text(item)
              .fontSize(16)
              .backgroundColor(0xF9CF93)
              .width('100%')
              .height('100%')
              .textAlign(TextAlign.Center)
          }
        }, (item: string) => item)

        GridItem() {
          Text('5')
            .fontSize(16)
            .backgroundColor(0xDBD0C0)
            .width('100%')
            .height('100%')
            .textAlign(TextAlign.Center)
        }.columnStart(1).columnEnd(4) // Set only the column numbers. The layout does not start from the first column.
      }
      .columnsTemplate('1fr 1fr 1fr 1fr 1fr')
      .rowsTemplate('1fr 1fr 1fr 1fr 1fr')
      .width('90%').height(300)
    }.width('100%').margin({ top: 5 })
  }
}

[h2]Example 2: Setting the Grid Item Style

This example shows how to set the grid item style using GridItemOptions.

// xxx.ets
@Entry
@Component
struct GridItemExample {
  @State numbers: String[] = ['0', '1', '2'];

  build() {
    Column({ space: 5 }) {
      Grid() {
        ForEach(this.numbers, (day: string) => {
          ForEach(this.numbers, (day: string) => {
            GridItem({style:GridItemStyle.NONE}) {
              Text(day)
                .fontSize(16)
                .width('100%')
                .height('100%')
                .textAlign(TextAlign.Center)
                .focusable(true)
            }
            .backgroundColor(0xF9CF93)
          }, (day: string) => day)
        }, (day: string) => day)
      }
      .columnsTemplate('1fr 1fr 1fr')
      .rowsTemplate('1fr 1fr')
      .columnsGap(4)
      .rowsGap(4)
      .width('60%')
      .backgroundColor(0xFAEEE0)
      .height(150)
      .padding('4vp')

      Grid() {
        ForEach(this.numbers, (day: string) => {
          ForEach(this.numbers, (day: string) => {
            GridItem({style:GridItemStyle.PLAIN}) {
              Text(day)
                .fontSize(16)
                .width('100%')
                .height('100%')
                .textAlign(TextAlign.Center)
                .focusable(true)
            }
            .backgroundColor(0xF9CF93)
          }, (day: string) => day)
        }, (day: string) => day)
      }
      .columnsTemplate('1fr 1fr 1fr')
      .rowsTemplate('1fr 1fr')
      .columnsGap(4)
      .rowsGap(4)
      .width('60%')
      .backgroundColor(0xFAEEE0)
      .height(150)
      .padding('4vp')
    }.width('100%').margin({ top: 5 })
  }
}