> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.

宫格组件是一种以宫格形式展示数据项的布局工具，支持灵活地添加组件、绑定数据和动态更新数据。宫格列表组件默认包含一个图片组件、一个容器组件和两个文本组件，你可根据业务需求自定义添加组件。
## 属性配置 {#edfcc06b}
宫格列表组件提供了丰富的属性配置选项，以下是一些关键属性配置说明。关于组件尺寸、位置、样式、指针、变换等通用属性的设置方法，请参考[设置组件属性和事件](/guides/set_properties_events)。
### 绑定数据源 {#540119d2}
为宫格列表组件支持绑定静态数据，或通过绑定工作流获取动态数据。

1. 为宫格列表组件绑定一个 Array 类型的数据源。
   例如将工作流的输出变量（例如 `output`）作为列表组件的数据源，该输出变量必须为 Array 类型。绑定工作流后，需要配置事件以触发工作流的调用，确保数据能够动态加载。
   
   ::::cols
   @col 33
      **工作流输出变量**
      ![Image=237x244](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/b441eff279df442f898300bf57ca928e~tplv-goo7wpa0wc-image.image)
   
   
   
   
   @col 33
   **绑定数据源**
   ![Image=295x328](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/860e6278ee84429097ff875c8e5d5f47~tplv-goo7wpa0wc-image.image)
   
   
   
   @col 33
   **配置事件**
   ![Image=425x614](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/4b196e6a523a4ab286a6bccf6c915e7a~tplv-goo7wpa0wc-image.image)
   
   ::::

2. 为宫格列表组件中的各个子组件绑定具体的数据字段。
   绑定数据源后，你可以通过 `item` 变量遍历和访问 Array 类型数据源中的每个元素。即你可以为列表组件中的各个子组件绑定具体的数据字段。例如为文本组件绑定数据字段 `{{item.name}}`，为图片组件绑定数据字段 `{{item.contentUrl}}`。具体示例，请参考[配置示例](/guides/grid_list_web#d86bbfb0)。
   :::tip 说明
   为图片组件绑定数据字段时，字段值需为图片地址，支持上传 `jpg`、`png`格式，暂不支持`svg`。
   :::


::::cols
@col 33
   **item 变量**
   ![Image=292x178](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/bbf9c443436f432c9f67e590afaea5cd~tplv-goo7wpa0wc-image.image)




@col 33
**为文本组件绑定数据字段**
![Image=293x156](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/0f7699f4cc01480998cc697729b3d142~tplv-goo7wpa0wc-image.image)



@col 33
**为图片组件绑定数据字段**
![Image=291x210](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/080a4c2c9f6941549e2ce14df7a02432~tplv-goo7wpa0wc-image.image)

::::

### 设置列数及间距 {#ce5e39ee}
宫格组件支持灵活调整布局，以满足不同场景的需求。具体功能包括：

* 固定列数：设置每行固定的宫格数量，确保布局的一致性。
* 动态列数：根据屏幕宽度或容器宽度自动调整每行的宫格数量，以实现响应式布局。
* 间距设置：支持通过**列间距**、**行间距**设置宫格之间的间距，灵活调整宫格布局。


::::cols
@col 50
**固定列表**
![Image=291x164](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/26dd4db311ba4a4fb81b1e00eb283dcc~tplv-goo7wpa0wc-image.image)



@col 50
**动态列数**
![Image=286x209](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/8660bc4ee09143fc8b5edd02107deeeb~tplv-goo7wpa0wc-image.image)

::::

### 调整组件 {#5cdb3267}
宫格列表组件默认包含一个图片组件、一个容器组件和两个文本组件。你可以根据业务需求，在宫格列表组件中自由添加其他组件或删除默认的子组件。当你在一个宫格中添加或删除子组件时，其他宫格中也会同步完成相同的操作。
例如在宫格列表组件中，删除原有的文本组件，然后添加一个容器组件和一个图标组件。
![Image=257x312](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/9254ef79672e47baa87729ea86e3428e~tplv-goo7wpa0wc-image.image)
### 隐藏组件 {#0c8d2830}
宫格列表组件的可见性可通过设置常用条件或表达式灵活控制，以实现特定场景下的隐藏或显示。

* 表达式方式
   * 设置为 false：显示组件。
   * 设置为 true：隐藏组件。
   * 设置为变量：通过变量值（true 或 false）动态控制组件的可见性。配置示例，请参考[隐藏组件](/guides/set_properties_events#46d8e38f)。
* 常用条件方式
   支持通过可视化界面设置条件，以控制组件的可见性。
   例如添加一个文本输入组件（Textarea1）和一个宫格列表（GridList1）组件，文本输入组件用于输入内容，宫格列表组件用于展示基于输入内容生成的图像。为了实现宫格列表组件内的图片展示时，就隐藏文本输入组件，你可以在文本输入组件的**可见性**属性中，添加条件 `Image1.src 不为空`。当宫格列表组件内的图片展示时，条件 `Image1.src 不为空` 变为 `true`，文本输入组件将自动隐藏。


::::cols
@col 49
   **可见性配置**
   ![Image=1494x445](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/15cd4099c63e45faae21dd4fb772fa99~tplv-goo7wpa0wc-image.image)




@col 49
**图片加载完成后隐藏文本输入组件**
![Image=1408x736](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/a5f7734452484af08b225d0b03966be0~tplv-goo7wpa0wc-image.image)


::::

## 事件设置 {#eab12c59}
通过配置宫格列表组件的事件，可以为宫格列表组件添加丰富的交互功能，以增强用户体验和界面的互动性。
<!-- @cols-width: 148,709 -->
| | | \
|**事件项** |**说明** |
|---|---|
| | | \
|事件类型 |支持以下事件类型： |\
| | |\
| |* 点击单元格时：当用户点击单元格时触发。 |\
| |* 加载时：当宫格列表组件完成加载时触发。 |
| | | \
|组件方法 |支持以下组件方法： |\
| | |\
| |* 设置隐藏：隐藏组件，使其不可见。 |\
| |* 滚动到视图：将组件滚动到可视区域内。 |

## 配置示例 {#d86bbfb0}
例如要使用悠船插件生成小狗图像，并在应用中以宫格形式展示小狗图像的生成效果，则你可以创建一个生成小狗图片的工作流，并通过宫格列表组件展示。具体操作如下：

1. 创建工作流。
   使用悠船插件（text2image）生成小狗图片，默认生成 4 张图像。其中，在**结束**节点中，设置输出变量 `output` 的值为悠船插件输出结果中的 `urls` ，其为 Array 类型，包含 4 张图像的 URL 地址。
   ![Image=1843x499](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/4e37ba2ea1cc47f48eb738baf760e369~tplv-goo7wpa0wc-image.image)
2. 绑定数据。
   1. 将工作流的输出变量 `output` 绑定到宫格列表组件上。
      ![Image=218x279](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/04984bacb1ef4125b15a4246f3cc0217~tplv-goo7wpa0wc-image.image)
   2. 为宫格列表组件添加**调用工作流**事件。
      例如配置事件为宫格列表组件加载时，即调用工作流，生成小狗图像。
      ![Image=230x352](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/b574768190d549d5a31c173d6bd30c52~tplv-goo7wpa0wc-image.image)
   3. 为宫格列表组件中的图片组件绑定数据字段 `{{ item }}`。
      `{{ item }}` 字段值为图片的 URL 地址。
      ![Image=209x209](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/f32f2cdb84b64ecbb57e6091f259d846~tplv-goo7wpa0wc-image.image)
   4. 删除宫格列表组件自带的两个文本组件。
3. 预览效果。
   以宫格列表形式展示图片生成结果。
   ![Image=372x386](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/b484c6edd8fb4eab9d3b22772207ec5e~tplv-goo7wpa0wc-image.image)