开发指南/消息卡片/搭建工具卡片组件/内容组件/标题
# 标题
本文介绍消息卡片搭建工具中的标题组件，以及该组件对应的 JSON 属性。
## 组件展示
在消息卡片搭建工具中，标题组件如下图所示。在工具内添加标题后，你可以编辑卡片的 **样式**、**内容**。
同一张卡片内仅支持添加一个标题。
## 参数说明
标题组件的参数说明如下表。
参数 | 是否必须 | 类型 | 描述
---|---|---|---
title | 是 | Object | 配置卡片的主标题信息。
└ tag | 是 | String | 文本标识。固定取值：plain_text
└ content | 否 | String | 卡片主标题内容。
**注意事项**：必须配置 `content` 或 `i18n` 两个属性的其中一个。如果同时配置仅生效 `i18n`。
└ i18n | 否 | \- | 国际化文本内容，其中：
* zh_cn：简体中文
* en_us：英文
* ja_jp：日文
* zh_hk：繁体中文（中国香港）
* zh_tw：繁体中文（中国台湾）
示例配置：
```JSON
{
"zh_cn": "这是主标题！",
"en_us": "It is the title!"
}
```
**注意事项**：必须配置 `content` 或 `i18n` 两个属性的其中一个。如果同时配置仅生效 `i18n`。
subtitle | 否 | String | 配置卡片的副标题信息。
**注意事项**：- 不允许只配置副标题内容。如果只配置副标题，则实际展示为主标题效果。
- 副标题内容最多 1 行，超长文案末尾使用 `...` 进行省略。
└ tag | 是 | String | 文本标识。固定取值：plain_text
└ content | 否 | String | 卡片副标题内容。
**注意事项**：必须配置 `content` 或 `i18n` 两个属性的其中一个。如果同时配置仅生效 `i18n`。
└ i18n | 否 | \- | 国际化文本内容，其中：
* zh_cn：简体中文
* en_us：英文
* ja_jp：日文
* zh_hk：繁体中文（中国香港）
* zh_tw：繁体中文（中国台湾）
示例配置：
```JSON
{
"zh_cn": "这是副标题！",
"en_us": "It is the title!"
}
```
**注意事项**：必须配置 `content` 或 `i18n` 两个属性的其中一个。如果同时配置仅生效 `i18n`。
icon | 否 | Object | 该对象用于设置标题的前缀图标。一个卡片仅可配置一个标题图标。
└ img_key | 否 | String | 前缀图标 key。
图标 key 的获取方式：调用[上传图片](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/image/create)接口，上传用于发送消息的图片，并在返回值中获取图片的 `image_key`。
template | 否 | String | 标题主题颜色。可选值与示例效果参见下文的 **标题样式表**。
text_tag_list | 否 | TextTagList | 标题的标签属性。最多可配置 3 个标签内容，如果配置的标签数量超过 3 个，则取前 3 个标签进行展示。标签展示顺序与数组顺序一致。
**注意事项**：- 标题标签在Lark V6.11 及以上版本开始生效。在旧版本客户端内将不会展示标题标签内容。
- `text_tag_list` 和 `i18n_text_tag_list` 只能配置其中之一。如果同时配置两个字段，则优先生效国际化配置。
└ tag | 否 | String | 标题标签的标识。固定取值：text_tag
└ text | 否 | text | 标题标签的内容。基于[文本组件](https://open.larksuite.com/document/ukTMukTMukTM/uUzNwUjL1cDM14SN3ATN)的 `plain_text` 模式定义内容。
示例值：
```json
"text": {
"tag": "plain_text",
"content": "这里是标签"
}
```
└ color | 否 | String | 标题标签的颜色，默认为蓝色（blue）。可选值与示例效果参见下文的 **标签样式表**。
i18n_text_tag_list | 否 | \- | 标题标签的国际化属性。你可以在该字段内配置多语言环境的标签内容。每个语言环境下最多可配置 3 个标签内容，如果配置的标签数量超过 3 个，则取前 3 个标签进行展示。标签展示顺序与数组顺序一致。
**注意事项**：- 标题标签在Lark V6.11 及以上版本开始生效。在旧版本客户端内将不会展示标题标签内容。
- `text_tag_list` 和 `i18n_text_tag_list` 只能配置其中之一。如果同时配置两个字段，则优先生效国际化配置。
支持设置的多语言枚举值如下：
* zh_cn：简体中文
* en_us：英文
* ja_jp：日文
* zh_hk：繁体中文（中国香港）
* zh_tw：繁体中文（中国台湾）
该字段的取值格式如下：
```json
{
"多语言枚举值": [
text_tag_list 结构体
]
}
```
示例值：
```json
// 如需使用该 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"
}
]
}
```
JSON 示例如下：
```json
// 如需使用该 JSON 示例，则注意需要手动清除 // 开头的注释
{
"header": { //在header中描述卡片的标题
"title": {
"tag": "plain_text",
"content": "This is header" //卡片标题文案内容
},
"template":"red" //卡片标题的主题色
}
}
```
## 标题样式表
消息卡片的标题样式由 `template` 参数的取值决定，详情参考下表。
Lark V5.0 及以后版本全局更新了 UI 风格，如果你在客户端查看的卡片样式与下表不一致，请升级至最新版Lark后重试。
template 取值 | 样式示例
---|---
blue | 
wathet | 
turquoise | 
green | 
yellow | 
orange | 
red | 
carmine | 
violet | 
purple | 
indigo | 
grey | 
default | 
## 标签样式表
消息卡片标签（`text_tag_list` 或 `i18n_text_tag_list`）的颜色样式由 `color` 字段定义，该字段支持的枚举值与示例样式如下表。
| color 取值 | 颜色效果 |
| --------- | ------------|
| neutral |  |
| blue |  |
| turquoise |  |
| lime |  |
| orange |  |
| violet |  |
| indigo |  |
| wathet |  |
| green |  |
| yellow |  |
| red |  |
| purple |  |
| carmine | 
## 样式建议
彩色标题适合在群聊中使用，对于需高亮提醒的卡片信息，可将标题配置为应用的品牌色或表达状态的语义色，增强信息的视觉锚点。
在单聊中，建议根据卡片的状态不同，配置不同的语义颜色标题。不建议在单聊中，每张卡片无差别的使用同一种颜色的标题。这样既无法起到强调作用，也可能引起阅读者的视觉焦虑。
你可以参考以下示例，配置不同语义下的主题颜色。
* 绿色（green）代表完成/成功
* 橙色（orange）代表警告/警示
* 红色（red）代表错误/异常
* 灰色（grey）代表失效
## 常见问题
### 如何配置标题图标、副标题？
在搭建工具中，目前不支持对标题图标（`icon`）、副标题（`subtitle`）进行可视化编辑，你可以在 JSON 编辑器中设置好标题样式与内容，并在工具右上角点击 **向我发送预览**，在客户端内查看实际生效的卡片效果。以下提供了示例代码供你参考：
- 不包含多语言内容的卡片
```json
// 如果你需要使用该 JSON 示例，则需要手动去除以 // 开头的注释内容
{
"header": {
"icon": { //为卡片标题配置前缀的图标资源
"img_key": "img_v2_718ccfc6-1180-41d7-a21d-1776dd053c8g"
},
"title": { //为卡片标题配置主标题文案内容
"tag": "plain_text",
"content": "这是title部分"
},
"subtitle": { //为卡片标题配置副标题文案内容
"tag": "plain_text",
"content": "这是subtitle部分"
},
"template": "red" //为卡片标题配置主题色
},
"elements": [
{
"tag": "markdown",
"content": "普通文本\n*斜体*\n**粗体**\n~~删除线~~"
}
]
}
```
- 包含多语言内容的卡片
```json
// 如果你需要使用该 JSON 示例，则需要手动去除以 // 开头的注释内容
{
"header": {
"icon": { //为卡片标题配置前缀的图标资源
"img_key": "img_v2_881d0c9c-8717-49a7-b075-1cca6562443g"
},
"title": { //为卡片标题配置多语言的主标题文案内容
"tag": "plain_text",
"i18n": {
"en_us": "英语环境下的主标题",
"ja_jp": "日语环境下的主标题",
"zh_cn": "中文环境下的主标题"
}
},
"subtitle": { //为卡片配置多语言的副标题文案内容
"tag": "plain_text",
"i18n": {
"en_us": "英语环境下的副标题",
"ja_jp": "日语环境下的副标题",
"zh_cn": "中文环境下的副标题"
}
},
"template": "red" //为卡片标题配置主题色
},
"elements": [
{
"tag": "markdown",
"content": "普通文本\n*斜体*\n**粗体**\n~~删除线~~"
}
]
}
```
### 如何配置标题标签？
在搭建工具内，目前不支持对标题标签（`text_tag_list` 或 `i18n_text_tag_list`）进行可视化编辑，也不支持通过 **向我发送预览** 按钮查看实际效果，仅支持通过编写 JSON 的方式定义标题标签。因此，你可以手动编辑卡片 JSON，然后通过开放平台提供的 OpenAPI （例如[发送消息](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/create)接口）发送消息卡片进行测试。
以下提供了示例代码供你参考：
- 不包含多语言内容的卡片
```json
{
"header": {
"text_tag_list": [
{
"tag": "text_tag",
"text": {
"tag": "plain_text",
"content": "标题标签"
},
"color": "carmine"
}
],
"title": {
"tag": "plain_text",
"content": "主标题"
},
"subtitle": {
"tag": "plain_text",
"content": "副标题"
},
"template": "red"
},
"elements": [
{
"tag": "div",
"text": {
"content": "正文内容",
"tag": "plain_text"
}
}
]
}
```
效果如下：
- 包含多语言内容的卡片
```json
{
"header": {
"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": "tagDemo"
},
"color": "carmine"
}
]
},
"title": {
"tag": "plain_text",
"i18n": {
"zh_cn": "主标题",
"en_us": "title"
}
},
"subtitle": {
"tag": "plain_text",
"i18n": {
"zh_cn": "副标题",
"en_us": "subtitle"
}
},
"template": "red"
},
"i18n_elements": {
"zh_cn": [
{
"tag": "div",
"text": {
"content": "正文内容",
"tag": "plain_text"
}
}
],
"en_us": [
{
"tag": "div",
"text": {
"content": "textDemo",
"tag": "plain_text"
}
}
]
}
}
```
效果如下：
- 简体中文环境
- 英文环境
