# 多图混排组件

Lark卡片支持多图混排组件。你可调用[上传图片](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/image/create)接口或在新版Lark卡片搭建工具中上传图片，获取图片的 key 传入多图混排组件中，使卡片内容更丰富。

本文档介绍多图混排组件的 JSON 2.0 结构，要查看历史 JSON 1.0 结构，参考[多图混排](https://open.larksuite.com/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-components/content-components/multi-image-laylout)。

![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/fb315779524d13ae504b7b7252acfd49_Bc8bJyGzyt.png?height=390&lazyload=true&maxWidth=300&width=559)

## 使用场景

在内容推送场景，你可能需要在卡片内组织编排多张图片。此时你可以使用多图混排组件，选择图片混排方式，快速构建多图样式。

双图混排 | 三图混排 | 四宫格图
---|---|---
  |   |  
六宫格图 | 九宫格图 |  
  |  

## 注意事项

为保证图片在聊天窗口中呈现的清晰度，建议你在组件中上传的图片遵从以下规范：

- 图片尺寸在 1500 × 3000 px 的范围内。
- 图片大小不超过 10 M。
- 图片的 `高度:宽度` 不超过 `16:9`。

## JSON 结构

多图混排的完整 JSON 2.0 结构如下所示：
```json
{
  "schema": "2.0", // 卡片 JSON 结构的版本。默认为 1.0。要使用 JSON 2.0 结构，必须显示声明 2.0。
  "body": {
    "elements": [
      {
        "tag": "img_combination",
        "element_id": "custom_id", // 操作组件的唯一标识。JSON 2.0 新增属性。用于在调用组件相关接口中指定组件。需开发者自定义。
        "margin": "0px 0px 0px 0px", // 组件的外边距。JSON 2.0 新增属性。默认值 "0"，支持范围 [-99,99]px。
        "combination_mode": "double", // 多图混排的方式。
        "combination_transparent": false, // 是否为透明底色。默认为 false，即图片为白色底色。
        "corner_radius": "12px", // 多图混排图片的圆角半径，单位是像素（px）。
        "img_list": [
          // 图片资源数组，顺序与图片排列顺序一致。
          {
            "img_key": "img_v3_0239_8347760e-3173-4072-b1aa-e4e7c835741j",
            "transparent": false // 是否为透明底色。默认为 false，即图片为白色底色。
          },
          {
            "img_key": "img_v3_0239_d9a9b734-57f8-4247-baf3-ae178b55f96j"
          }
        ]
      }
    ]
  }
}
```

## 字段说明

多图混排组件的字段说明如下表。

名称 | 必须 | 类型 | 默认值 | 描述
---|---|---|---|---
tag | 是 | String | / | 多图混排组件的标签，固定取值：`img_combination`。
element_id | 否 | String | 空 | 操作组件的唯一标识。JSON 2.0 新增属性。用于在调用[组件相关接口](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/cardkit-v1/card-element/create)中指定组件。在同一张卡片内，该字段的值全局唯一。仅允许使用字母、数字和下划线，必须以字母开头，不得超过 20 字符。
margin | 否 | String | 0 | 组件的外边距。JSON 2.0 新增属性。值的取值范围为 [-99,99]px。可选值：<br>- 单值，如 "10px"，表示组件的四个外边距都为 10 px。<br>- 双值，如 "4px 0"，表示组件的上下外边距为 4 px，左右外边距为 0 px。使用空格间隔（边距为 0 时可不加单位）。<br>- 多值，如 "4px 0 4px 0"，表示组件的上、右、下、左的外边距分别为 4px，12px，4px，12px。使用空格间隔。
combination_mode | 是 | String | 空 | 多图混排的方式，可取值：<br>- double：双图混排，最多可排布两张图。<br>- triple：三图混排，最多可排布三张图。<br>- bisect：等分双列图混排，每行两个等大的正方形图，最多可排布三行，即六张图。<br>- trisect：等分三列图混排，每行三个等大的正方形图，最多可排布三行，即九张图。<br>**注意**：<br>-   若上传的图片数量超过混排方式可容纳的上限，则系统将根据图片上传的顺序，优先展示排列顺序中靠前的图片。超出上限的图片将不再显示。<br>- 若上传的图片数量未达到混排方式可容纳的上限，则未排布的部分将保留空白。
combination_transparent | 否 | Boolean | false | 是否为透明底色。默认为 false，即图片为白色底色。
corner_radius | 否 | String | / | 多图混排图片的圆角半径，单位是像素（px）。取值遵循以下格式：<br>- [0,∞]px<br>- [0,100]%
img_list | 是 | Object | 空 | 图片资源的 `img_key` 数组，顺序与图片排列顺序一致。
└ img_key | 是 | String | / | 图片资源的 Key。你可以调用[上传图片](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/image/create)接口或在搭建工具中上传图片，获取图片的 key。

## 示例代码

### 双图混排效果示例

将以下示例代码中的 `img_key` 替换为实际的图片 Key，即可实现如下图示例的卡片效果：

![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/8a03a4edd6a0813bced92cd383061ab8_6AePbfDCGW.png?height=506&lazyload=true&maxWidth=400&width=1081)

```json
{
  "schema": "2.0",
  "body": {
    "direction": "vertical",
    "padding": "12px 12px 12px 12px",
    "elements": [
      {
        "tag": "img_combination",
        "combination_mode": "double",
        "img_list": [
          {
            "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg"
          },
          {
            "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg"
          }
        ],
        "combination_transparent": false,
        "margin": "0px 0px 0px 0px"
      }
    ]
  }
}
```

### 三图混排效果示例

将以下示例代码中的 `img_key` 替换为实际的图片 Key，即可实现如下图示例的卡片效果：

![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/fb315779524d13ae504b7b7252acfd49_cQR9wIHOXZ.png?height=390&lazyload=true&maxWidth=400&width=559)

```json
{
  "schema": "2.0",
  "body": {
    "direction": "vertical",
    "padding": "12px 12px 12px 12px",
    "elements": [
      {
        "tag": "img_combination",
        "combination_mode": "triple",
        "img_list": [
          {
            "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg"
          },
          {
            "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg"
          },
          {
            "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg"
          }
        ],
        "combination_transparent": false,
        "margin": "0px 0px 0px 0px"
      }
    ]
  }
}
```

### **等分双列效果示例**

将以下示例代码中的 `img_key` 替换为实际的图片 Key，即可实现如下图示例的卡片效果：

![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/02236d7183ff1ca900ffc37dbec338dc_FpogForok4.png?height=819&lazyload=true&maxWidth=300&width=559)

```json
{
  "schema": "2.0",
  "body": {
    "direction": "vertical",
    "padding": "12px 12px 12px 12px",
    "elements": [
      {
        "tag": "img_combination",
        "combination_mode": "bisect",
        "img_list": [
          {
            "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg"
          },
          {
            "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg"
          },
          {
            "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg"
          },
          {
            "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg"
          },
          {
            "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg"
          },
          {
            "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg"
          }
        ],
        "combination_transparent": false,
        "margin": "0px 0px 0px 0px"
      }
    ]
  }
}
```

### 等分三列效果示例

将以下示例代码中的 `img_key` 替换为实际的图片 Key，即可实现如下图示例的卡片效果：

![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/7473f1d9907913c279f796e6022f7a95_Z5qFUWHIbL.png?height=212&lazyload=true&maxWidth=400&width=559)
```json
{
  "schema": "2.0",
  "body": {
    "direction": "vertical",
    "padding": "12px 12px 12px 12px",
    "elements": [
      {
        "tag": "img_combination",
        "combination_mode": "trisect",
        "img_list": [
          {
            "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg"
          },
          {
            "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg"
          },
          {
            "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg"
          },
          {
            "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg"
          },
          {
            "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg"
          },
          {
            "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg"
          },
          {
            "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg"
          },
          {
            "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg"
          },
          {
            "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg"
          }
        ],
        "combination_transparent": false,
        "margin": "0px 0px 0px 0px"
      }
    ]
  }
}
```