# 新增组件

为指定卡片实体新增组件，以扩展卡片内容，如在卡片中添加一个点击按钮。

## 使用限制

- 调用该接口时，不支持将卡片设置为独享卡片模式。即不支持将卡片 JSON 数据中的 `update_multi` 属性设置为 `false`。
- 调用该接口的应用身份（tenant_access_token）需与创建目标卡片实体的应用身份一致。

## 请求

基本 |  
---|---
HTTP URL | https://open.feishu.cn/open-apis/cardkit/v1/cards/:card_id/elements
HTTP Method | POST
接口频率限制 | [1000 次/分钟、50 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App、Store App
权限要求<br>**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 创建与更新卡片(cardkit:card:write)

### 请求头

名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`<br>**值格式**："Bearer `access_token`"<br>**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"<br>[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | 是 | **固定值**："application/json; charset=utf-8"

### 路径参数

名称 | 类型 | 描述
---|---|---
card_id | string | 要新增组件的卡片实体 ID。通过[创建卡片实体](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/cardkit-v1/card/create)获取<br>**示例值**："7355439197428236291"<br>**数据校验规则**：<br>- 长度范围：`1` ～ `20` 字符

### 请求体

名称 | 类型 | 必填 | 描述
---|---|---|---
type | string | 是 | 添加组件的方式。<br>**示例值**："insert_after"<br>**可选值有**：<br>- insert_before：在目标组件前插入<br>- insert_after：在目标组件后插入<br>- append：在卡片或容器组件末尾添加
target_element_id | string | 否 | 目标组件的 ID。 填写规则如下所示：<br>- 当 `type` 为 `insert_before`、`insert_after` 时，字段必填，为用于定位的目标组件<br>-  当 `type` 为 `append` 时，该字段仅支持容器类组件，用于指定在末尾添加的目标组件。若未填写，则默认在卡片 body 末尾添加<br>**示例值**："markdown_1"<br>**数据校验规则**：<br>- 长度范围：`0` ～ `20` 字符
uuid | string | 否 | 幂等 ID，可通过传入唯一的 UUID 以保证相同批次的操作只进行一次。<br>**示例值**："a0d69e20-1dd1-458b-k525-dfeca4015204"<br>**数据校验规则**：<br>- 长度范围：`1` ～ `64` 字符
sequence | int | 是 | 操作卡片的序号。用于保证多次更新的时序性。<br>**注意**：<br>请确保在通过卡片 OpenAPI 操作同一张卡片时，sequence 的值相较于上一次操作严格递增。<br>**数据校验规则**：int32 范围（ `1`~`2147483647`）内的正整数。<br>**示例值**：1
elements | string | 是 | 添加的组件列表。<br>**注意**：<br>- 以下示例值未转义，使用时请注意将其转为 JSON 序列化后的字符串。<br>- 本参数仅支持[卡片 JSON 2.0 结构](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-structure)。<br>**示例值**："[{\"tag\":\"button\",\"element_id\":\"button_1\",\"text\":{\"tag\":\"plain_text\",\"content\":\"查看更多\"},\"type\":\"default\",\"width\":\"default\",\"size\":\"medium\",\"behaviors\":[{\"type\":\"open_url\",\"default_url\":\"https://open.feishu.cn/?lang=zh-CN\",\"pc_url\":\"\",\"ios_url\":\"\",\"android_url\":\"\"}]}]"<br>**数据校验规则**：<br>- 长度范围：`1` ～ `1000000` 字符

### 请求体示例
```json
{
    "type": "insert_after",
    "target_element_id": "markdown_1",
    "uuid": "a0d69e20-1dd1-458b-k525-dfeca4015204",
    "sequence": 1,
    "elements": "[{\"tag\":\"button\",\"element_id\":\"button_1\",\"text\":{\"tag\":\"plain_text\",\"content\":\"查看更多\"},\"type\":\"default\",\"width\":\"default\",\"size\":\"medium\",\"behaviors\":[{\"type\":\"open_url\",\"default_url\":\"https://open.feishu.cn/?lang=zh-CN\",\"pc_url\":\"\",\"ios_url\":\"\",\"android_url\":\"\"}]}]"
}
```

## 响应

### 响应体

名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-

### 响应体示例
```json
{
    "code": 0,
    "msg": "success",
    "data": {}
}
```

### 错误码

HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
400 | 10002 | Your request contains an invalid request parameter. | 参数错误，请根据接口返回的错误信息并参考本文档检查输入参数。
400 | 200740 | The card entity does not exist | 卡片实体不存在。请检查实体 ID 是否正确。
400 | 200750 | The card entity has expired | 卡片实体已过期。卡片实体的有效期为 14 天。即创建卡片实体超出 14 天后，你将无法调用相关接口操作卡片。请再次创建一个新的卡片实体。
400 | 200770 | UUID conflict | UUID 冲突。请传入唯一的 UUID 以保证相同批次的操作只进行一次。
400 | 200810 | The card is in an ongoing interaction and cannot be updated | 在用户点击卡片[请求回调](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-callback-communication)交互期间，卡片无法实现流式更新。请等待交互结束后再尝试更新卡片。
400 | 200510 | Card streaming timeout | 卡片流式更新模式因超时自动关闭。你可调用[更新卡片配置](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/cardkit-v1/card/settings) 将 `streaming_mode` 字段值设置为 `true`。
400 | 200860 | Card content exceeds limit. | 卡片体积超限。请将卡片大小控制在 30KB 以内。
400 | 300301 | Duplicate element_id in card component. | 卡片内部组件 ID （即 element_id）重复。
400 | 300302 | update_multi property is false | 卡片全局属性 update_multi 为 false。在流式更新模式下，卡片全局属性 update_multi 需设置为 true。
400 | 200220 | Failed to generate card content | 生成卡片内容失败。请检查卡片 JSON 格式是否有误。
400 | 300305 | The number of card components exceeds 200 | 超出卡片组件限制。卡片 JSON 2.0 结构中，一张卡片最多支持 200 个元素（如 tag 为 plain_text 的文本元素）或组件。请将组件和元素的数量之和控制在 200 个以内。
400 | 300307 | The card DSL is empty | 卡片 JSON 数据为空。请检查数据。
400 | 300311 | The current application does not have permission to update/use this card | 当前应用没有更新或使用该卡片的权限。请使用创建卡片实体的应用调用相关 OpenAPI 发送、操作卡片。
400 | 300315 | Failed to add element | 添加组件失败。请根据接口返回的错误信息检查输入参数。
400 | 300317 | The sequence number for operating on the card did not increment consecutively | 操作卡片的序号（sequence）未按顺序递增。请确保在通过卡片 OpenAPI 操作同一张卡片时，sequence 的值相较于上一次操作严格递增。
400 | 300120 | Server Internal Error | 服务内部错误。请稍后重试。仍然出现可联系[技术支持](https://applink.feishu.cn/TLJpeNdW)。