# 标题组件
卡片的标题组件支持添加卡片主标题、副标题、后缀标签和标题图标。
本文档介绍标题组件的 JSON 2.0 结构，要查看历史 JSON 1.0 结构，参考[标题](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-components/content-components/title)。
## 注意事项
同一张卡片仅支持添加一个标题组件。
## 组件属性
### JSON 结构
标题组件的完整 JSON 2.0 结构如下所示：
```json
{
"schema": "2.0", // 卡片 JSON 结构的版本。默认为 1.0。要使用 JSON 2.0 结构，必须显示声明 2.0。
"header": {
"title": {
// 卡片主标题。必填。要为标题配置多语言，参考配置卡片多语言文档。
"tag": "plain_text", // 文本类型的标签。可选值：plain_text 和 lark_md。
"content": "示例标题" // 标题内容。
},
"subtitle": {
// 卡片副标题。可选。
"tag": "plain_text", // 文本类型的标签。可选值：plain_text 和 lark_md。
"content": "示例文本" // 标题内容。
},
"text_tag_list": [
// 标题后缀标签，最多设置 3 个 标签，超出不展示。可选。
{
"tag": "text_tag",
"element_id": "custom_id", // 操作元素的唯一标识。用于在调用组件相关接口中指定元素。需开发者自定义。
"text": {
// 标签内容
"tag": "plain_text",
"content": "标签 1"
},
"color": "neutral" // 标签颜色
}
],
"i18n_text_tag_list": {
// 多语言标题后缀标签。每个语言环境最多设置 3 个 tag，超出不展示。可选。同时配置原字段和国际化字段，优先生效多语言配置。
"zh_cn": [],
"en_us": [],
"ja_jp": [],
"zh_hk": [],
"zh_tw": []
},
"template": "blue", // 标题主题样式颜色。支持 "blue"|"wathet"|"turquoise"|"green"|"yellow"|"orange"|"red"|"carmine"|"violet"|"purple"|"indigo"|"grey"|"default"。默认值 default。
"icon": { // 前缀图标。
"tag": "standard_icon", // 图标类型。
"token": "chat-forbidden_outlined", // 图标的 token。仅在 tag 为 standard_icon 时生效。
"color": "orange", // 图标颜色。仅在 tag 为 standard_icon 时生效。
"img_key": "img_v2_38811724" // 图片的 key。仅在 tag 为 custom_icon 时生效。
},
"padding": "12px 8px 12px 8px" // 标题组件的内边距。JSON 2.0 新增属性。默认值 "12px"，支持范围 [0,99]px。
}
}
```
### 字段说明
标题组件的字段说明如下表。
名称 | 必填 | 类型 | 说明
---|---|---|---
title | 是 | Object | 配置卡片的主标题信息。
**注意**：如果只配置副标题，则实际展示为主标题效果。
└ tag | 是 | String | 文本类型的标签。可取值：
- `plain_text`：普通文本内容或[表情](https://www.feishu.cn/docx/doxcnG6utI72jB4eHJF1s5IgVJf)
- `lark_md`：支持以下 Markdown 语法的文本内容：
- @指定人：
```
```
- @所有人：``
- emoji：😁😢🌞💼🏆❌✅。直接复制表情即可。了解更多 emoji 表情，参考 [Emoji 表情符号大全](https://www.feishu.cn/docx/doxcnG6utI72jB4eHJF1s5IgVJf)。
- 飞书表情：如 `:OK:`。参考[表情文案说明](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message-reaction/emojis-introduce)。
└ content | 否 | String | 卡片主标题内容。要为标题配置多语言，参考[配置卡片多语言](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/configure-multi-language-content)。
**注意**：主标题内容最多四行，超出四行的内容用 `...` 省略。
subtitle | 否 | Object | 配置卡片的副标题信息。
**注意**：如果只配置副标题，则实际展示为主标题效果。
└ tag | 是 | String | 文本类型的标签。可取值：
- `plain_text`：普通文本内容或[表情](https://www.feishu.cn/docx/doxcnG6utI72jB4eHJF1s5IgVJf)
- `lark_md`：支持以下 Markdown 语法的文本内容：
- @指定人：
```
```
- @所有人：``
- emoji：😁😢🌞💼🏆❌✅。直接复制表情即可。了解更多 emoji 表情，参考 [Emoji 表情符号大全](https://www.feishu.cn/docx/doxcnG6utI72jB4eHJF1s5IgVJf)。
- 飞书表情：如 `:OK:`。参考[表情文案说明](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message-reaction/emojis-introduce)。
└ content | 否 | String | 卡片副标题内容。要为标题配置多语言，参考[配置卡片多语言](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/configure-multi-language-content)。
**注意**：副标题内容最多一行，超出一行的内容用 `...` 省略。
text_tag_list | 否 | TextTagList | 添加标题的后缀标签。最多可添加 3 个标签内容，如果配置的标签数量超过 3 个，则取前 3 个标签进行展示。标签展示顺序与数组顺序一致。
**注意**：
`text_tag_lis`t 和 `i18n_text_tag_list` 只能配置其中之一。如果同时配置仅生效 `i18n_text_tag_list`。
└ tag | 是 | String | 后缀标签的标识。固定取值：`text_tag`。
└ element_id | 否 | String | 操作组件的唯一标识。JSON 2.0 新增属性。用于在调用[组件相关接口](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/cardkit-v1/card-element/create)中指定组件。在同一张卡片内，该字段的值全局唯一。仅允许使用字母、数字和下划线，必须以字母开头，不得超过 20 字符。
└ text | 否 | Text Object | 后缀标签的内容。基于文本组件的 plain_text 模式定义内容。
示例值：
```JSON
"text": {
"tag": "plain_text",
"content": "这里是标签"
}
```
└ color | 否 | String | 后缀标签的颜色，默认为蓝色（blue）。可选值与示例效果参见下文的后缀标签颜色枚举。
i18n_text_tag_list | 否 | Object | 配置后缀标签的多语言属性，在所需语种字段下添加完整的后缀标签结构体即可。每个语言最多可配置 3 个标签内容，如果配置的标签数量超过 3 个，则取前 3 个标签进行展示。标签展示顺序与数组顺序一致。支持设置的多语言枚举值如下：
- zh_cn：简体中文
- en_us：英文
- ja_jp：日文
- zh_hk：繁体中文（中国香港）
- zh_tw：繁体中文（中国台湾）
- id_id: 印尼语
- vi_vn: 越南语
- th_th: 泰语
- pt_br: 葡萄牙语
- es_es: 西班牙语
- ko_kr: 韩语
- de_de: 德语
- fr_fr: 法语
- it_it: 意大利语
- ru_ru: 俄语
- ms_my: 马来语
示例配置：
```json
"i18n_text_tag_list": {
"zh_cn": [
{
"tag": "text_tag",
"text": {
"tag": "plain_text",
"content": "标签内容"
},
"color": "carmine"
}
],
"en_us": [
{
"tag": "text_tag",
"text": {
"tag": "plain_text",
"content": "Tag content"
},
"color": "carmine"
}
]
}
```
**注意**：
`text_tag_list` 和 `i18n_text_tag_list` 只能配置其中之一。如果同时配置两个字段，则优先生效多语言配置。
template | 否 | String | 配置标题主题颜色。可选值与示例效果参见下文的标题主题样式枚举。
icon | 否 | Object | 添加图标作为文本前缀图标。支持自定义或使用图标库中的图标。
└ tag | 否 | String | 图标类型的标签。可取值：
- `standard_icon`：使用图标库中的图标。
- `custom_icon`：使用用自定义图片作为图标。
└ token | 否 | String | 图标库中图标的 token。当 `tag` 为 `standard_icon` 时生效。枚举值参见[图标库](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/enumerations-for-icons)。
└ color | 否 | String | 图标的颜色。支持设置线性和面性图标（即 token 末尾为 `outlined` 或 `filled` 的图标）的颜色。当 `tag` 为 `standard_icon` 时生效。枚举值参见[颜色枚举值](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/enumerations-for-fields-related-to-color)。
└ img_key | 否 | String | 自定义前缀图标的图片 key。当 `tag` 为 `custom_icon` 时生效。
图标 key 的获取方式：调用[上传图片](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/image/create)接口，上传用于发送消息的图片，并在返回值中获取图片的 image_key。
padding | 否 | String | 标题组件的内边距。默认为 12px。值的取值范围为 [-99,99]px。可选值：
- 单值，如 "10px"，表示容器的四个外边距都为 10 px。
- 双值，如 "4px 0"，表示容器的上下外边距为 4 px，左右外边距为 0 px。使用空格间隔（边距为 0 时可不加单位）。
- 多值，如 "4px 0 4px 0"，表示容器的上、右、下、左的外边距分别为 4px，12px，4px，12px。使用空格间隔。
## Demo 示例
以下 JSON 2.0 结构的示例代码可实现如下图所示的卡片效果：
```json
{
"schema": "2.0",
"body": {
"elements": [
{
"tag": "div",
"text": {
"tag": "plain_text",
"content": "示例文本"
}
}
]
},
"header": {
"title": {
"tag": "lark_md",
"content": ":Partying:卡片主标题 "
},
"subtitle": {
"tag": "plain_text",
"content": "卡片副标题"
},
"text_tag_list": [
{
"tag": "text_tag",
"text": {
"tag": "plain_text",
"content": "标签 1"
},
"color": "blue"
},
{
"tag": "text_tag",
"text": {
"tag": "plain_text",
"content": "标签 2"
},
"color": "turquoise"
},
{
"tag": "text_tag",
"text": {
"tag": "plain_text",
"content": "标签 3"
},
"color": "orange"
}
],
"template": "blue",
"icon": {
"tag": "standard_icon",
"token": "larkcommunity_colorful"
},
"padding": "12px"
}
}
```
## 枚举
### 标题主题样式枚举
标题组件中的 `template` 字段决定了卡片的标题主题样式。你可参考下表了解 `template` 的枚举值和对应的主题样式。
| 枚举值 | 主题样式示例 |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| blue |  |
| wathet |  |
| turquoise |  |
| green |  |
| yellow |  |
| orange |  |
| red |  |
| carmine |  |
| violet |  |
| purple |  |
| indigo |  |
| grey |  |
| default |  |
### 后缀标签颜色枚举
标题的后缀标签的颜色样式由`text_tag_list` 或 `i18n_text_tag_list` 中的 `color` 字段定义，该字段支持的枚举值与示例样式如下表所示。
| 枚举值 | 颜色效果 |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| neutral |  |
| blue |  |
| turquoise |  |
| lime |  |
| orange |  |
| violet |  |
| indigo |  |
| wathet |  |
| green |  |
| yellow |  |
| red |  |
| purple |  |
| carmine |  |
### 图标枚举
查看字段 `icon.token` 的枚举，参考[图标库](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/enumerations-for-icons)。
### 图标颜色枚举
你可通过 `icon.color` 字段设置图标颜色。查看 `color` 枚举，参考[颜色枚举值](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/enumerations-for-fields-related-to-color)。
## 标题主题样式建议
在群聊中，可使用彩色标题。对于需高亮提醒的卡片信息，可将标题配置为应用的品牌色或表达状态的语义色，增强信息的视觉锚点。
在单聊中，建议根据卡片的状态配置标题样式。你可以参考以下示例，配置不同语义下的主题样式。
| **样式颜色** | **语义** | **示例** |
| ---------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 绿色（green） | 完成或成功。 |  |
| 橙色（orange） | 警告或警示。 |  |
| 红色（red） | 错误或异常。 |  |
| 灰色（grey） | 失效。 | 