TextBlock 元素

注释

你是构建由自适应卡片提供支持的 Copilot、Teams 或 Outlook 方案吗？ 访问 自适应卡片文档中心，这是所有自适应卡需求的新一站式商店！它包含要查找的所有资源，包括许多新功能的完整文档，如响应式布局、图标、锁屏提醒、轮播、图表等！

本页提供关于自适应卡片架构中TextBlock元素的文档。

有关辅助功能的重要说明： 在架构版本 1.3 中，我们在输入中引入了一个标签属性以提高辅助功能。如果你 面向的 Host 应用 支持 v1.3，则应使用标签而不是 TextBlock ，如以下示例所示。大多数主机应用更新到最新版本后，我们将相应地更新示例。

TextBlock

显示文本，允许控制字体大小、粗细和颜色。

TextBlock 属性

资产	类型	必选	Description	版本
类型	`"TextBlock"`	是的	必须是 `"TextBlock"`。	1.0
text	`string`	是的	要显示的文本。支持 markdown 的子集（https://aka.ms/ACTextFeatures）	1.0
颜色	`Colors?`	否	控制 `TextBlock` 元素的颜色。	1.0
fontType	`FontType?`	否	要用于呈现的字体类型	1.2
horizontalAlignment	`HorizontalAlignment?`	否	控制水平文本对齐方式。如果未指定，则 horizontalAlignment 的值继承自父容器。如果没有父容器设置“horizontalAlignment”（水平对齐），则默认设置为“Left”（左对齐）。	1.0
isSubtle	`boolean?`	否	如果`true`，则显示的文本稍显低调，不那么显眼。	1.0
maxLines	`number`	否	指定要显示的最大行数。	1.0
大小	`FontSize?`	否	控制文本的大小。	1.0
weight	`FontWeight?`	否	控制 `TextBlock` 元素的权重。	1.0
包装	`boolean`	否	如果 `true`，则允许文本换行。否则，文本将被截断。	1.0
style	`TextBlockStyle?`	否，默认值： `"default"`	此 TextBlock 的样式旨在提高可访问性。	1.5

继承的属性

资产	类型	必选	Description	版本
回退	`Element`、`FallbackOption`	否	描述当遇到未知元素或无法满足此元素或任何子元素的需求时要执行的措施。	1.2
height	`BlockElementHeight`	否	指定元素的高度。	1.1
separator	`boolean`	否	当`true`时，在元素顶部绘制一条分隔线。	1.0
间距	`Spacing`	否	控制此元素与上一个元素之间的间距量。	1.0
id	`string`	否	与项关联的唯一标识符。	1.0
isVisible	`boolean`	否，默认值： `true`	如果 `false`，将从可视化树中删除此项。	1.2
需要	`Dictionary<string>`	否	一系列键/值对，说明项目所需功能及其相应的最低版本。当某个功能缺失或版本不够时，将触发降级。	1.2

Example

基本 TextBlock 示例（JSON）

{
	"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
	"type": "AdaptiveCard",
	"version": "1.0",
	"body": [
		{
			"type": "TextBlock",
			"text": "This is some text",
			"size": "large"
		},
		{
			"type": "TextBlock",
			"text": "It doesn't wrap by default",
			"weight": "bolder"
		},
		{
			"type": "TextBlock",
			"text": "So set **wrap** to true if you plan on showing a paragraph of text",
			"wrap": true
		},
		{
			"type": "TextBlock",
			"text": "You can also use **maxLines** to prevent it from getting out of hand",
			"wrap": true,
			"maxLines": 2
		},
		{
			"type": "TextBlock",
			"text": "You can even draw attention to certain text with color",
			"wrap": true,
			"color": "attention"
		}
	]
}

属性

文本消息

要显示的文本。支持 markdown 的子集（https://aka.ms/ACTextFeatures）

类型：string
必需：是

color

控制 TextBlock 元素的颜色。

类型：Colors?
必需：否
允许的值：
- "default"
- "dark"
- "light"
- "accent"
- "good"
- "warning"
- "attention"

颜色示例（JSON）

{
	"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
	"type": "AdaptiveCard",
	"version": "1.0",
	"body": [
		{
			"type": "TextBlock",
			"text": "color: default",
			"color": "default"
		},
		{
			"type": "TextBlock",
			"text": "color: accent",
			"color": "accent"
		},
		{
			"type": "TextBlock",
			"text": "color: good",
			"color": "good"
		},
		{
			"type": "TextBlock",
			"text": "color: warning",
			"color": "warning"
		},
		{
			"type": "TextBlock",
			"text": "color: attention",
			"color": "attention"
		},
		{
			"type": "TextBlock",
			"text": "color: light",
			"color": "light"
		},
		{
			"type": "TextBlock",
			"text": "color: dark",
			"color": "dark"
		}
	]
}

字体类型

要用于呈现的字体类型

类型：FontType?
版本：1.2
必需：否
允许的值：
- "default"
- "monospace"

FontType 示例（JSON）

{
	"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
	"type": "AdaptiveCard",
	"version": "1.2",
	"body": [
		{
			"type": "TextBlock",
			"text": "Font type not set."
		},
		{
			"type": "TextBlock",
			"text": "Font type set to *default*.",
			"fontType": "default"
		},
		{
			"type": "TextBlock",
			"text": "Font type set to *monospace*.",
			"fontType": "monospace"
		}
	]
}

horizontalAlignment

控制水平文本对齐方式。如果未指定，则 horizontalAlignment 的值继承自父容器。如果没有父容器设置“horizontalAlignment”（水平对齐），则默认设置为“Left”（左对齐）。

类型：HorizontalAlignment?
必需：否
允许的值：
- "left"
- "center"
- "right"

HorizontalAlignment 示例（JSON）

{
	"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
	"type": "AdaptiveCard",
	"version": "1.0",
	"body": [
		{
			"type": "TextBlock",
			"text": "**horizontalAlignment:left**",
			"horizontalAlignment": "left"
		},
		{
			"type": "TextBlock",
			"text": "**horizontalAlignment:center**",
			"horizontalAlignment": "center"
		},
		{
			"type": "TextBlock",
			"text": "**horizontalAlignment:right**",
			"horizontalAlignment": "right"
		}
	]
}

isSubtle

如果true，则显示的文本稍显低调，不那么显眼。

类型：boolean?
必需：否

isSubtle 示例（JSON）

{
	"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
	"type": "AdaptiveCard",
	"version": "1.0",
	"body": [
		{
			"type": "TextBlock",
			"text": "isSubtle:false",
			"isSubtle": false
		},
		{
			"type": "TextBlock",
			"text": "isSubtle:true",
			"isSubtle": true
		}
	]
}

maxLines

指定要显示的最大行数。

类型：number
必需：否

maxLines 示例（JSON）

{
	"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
	"type": "AdaptiveCard",
	"version": "1.0",
	"body": [
		{
			"type": "TextBlock",
			"text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
			"wrap": true,
			"maxLines": 1
		},
		{
			"type": "TextBlock",
			"text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
			"wrap": true,
			"maxLines": 2
		}
	]
}

size

控制文本的大小。

类型：FontSize?
必需：否
允许的值：
- "default"
- "small"
- "medium"
- "large"
- "extraLarge"

大小示例（JSON）

{
	"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
	"type": "AdaptiveCard",
	"version": "1.0",
	"body": [
		{
			"type": "TextBlock",
			"text": "size:default"
		},
		{
			"type": "TextBlock",
			"text": "size:small",
			"size": "small"
		},
		{
			"type": "TextBlock",
			"text": "size:default",
			"size": "default"
		},
		{
			"type": "TextBlock",
			"text": "size:medium",
			"size": "medium"
		},
		{
			"type": "TextBlock",
			"text": "size:large",
			"size": "large"
		},
		{
			"type": "TextBlock",
			"text": "size:extraLarge",
			"size": "extraLarge"
		}
	]
}

weight

控制 TextBlock 元素的权重。

类型：FontWeight?
必需：否
允许的值：
- "default"
- "lighter"
- "bolder"

权重示例（JSON）

{
	"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
	"type": "AdaptiveCard",
	"version": "1.0",
	"body": [
		{
			"type": "TextBlock",
			"text": "weight: lighter",
			"weight": "lighter"
		},
		{
			"type": "TextBlock",
			"text": "weight: default",
			"weight": "default"
		},
		{
			"type": "TextBlock",
			"text": "weight: bolder",
			"weight": "bolder"
		}
	]
}

包装

如果 true，则允许文本换行。否则，文本将被截断。

类型：boolean
必需：否

包装示例（JSON）

{
	"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
	"type": "AdaptiveCard",
	"version": "1.0",
	"body": [
		{
			"type": "TextBlock",
			"text": "**wrap: false** Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat",
			"wrap": false
		},
		{
			"type": "TextBlock",
			"text": "**wrap: true** Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
			"wrap": true
		}
	]
}

样式

此 TextBlock 的样式旨在提高可访问性。

类型：TextBlockStyle?
版本：1.5
必需：否，默认值： "default"
允许的值：
- "default"：这是不提供特殊样式或行为的默认样式。
- "heading"：TextBlock是一个标题。这将应用标题样式默认值，并将标题标记为 TextBlock 可访问性标题。

样式示例（JSON）

{
	"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
	"type": "AdaptiveCard",
	"version": "1.5",
	"body": [
		{
			"type": "TextBlock",
			"text": "Style set to heading",
			"style": "heading",
			"wrap": true
		},
		{
			"type": "TextBlock",
			"text": "Style set to heading, color set to good",
			"style": "heading",
			"color": "good",
			"wrap": true
		},
		{
			"type": "TextBlock",
			"text": "Style set to default",
			"style": "default",
			"wrap": true
		},
		{
			"type": "TextBlock",
			"text": "Style unset",
			"wrap": true
		}
	]
}

后备

描述遇到未知元素时或无法满足该元素或任何子元素的要求时需要执行的操作。

类型： Element， FallbackOption
版本：1.2
必需：否
允许的值：
- ActionSet、ColumnSet、Container、FactSet、Image、ImageSet、Input.ChoiceSet、Input.Date、Input.Number、Input.Text、Input.Time、Input.Toggle、Media、RichTextBlock、Table、TextBlock
- "drop"：导致遇到未知元素时立即删除此元素。未知元素不会进一步冒泡。

身高

指定元素的高度。

类型：BlockElementHeight
版本：1.1
必需：否
允许的值：
- "auto"：容器的高度由其内容的高度决定。
- "stretch"：容器将高度拉伸到父容器的可用剩余高度。

分隔符

当true时，在元素顶部绘制一条分隔线。

类型：boolean
必需：否

间距

控制此元素与上一个元素之间的间距量。

类型：Spacing
必需：否
允许的值：
- "default"、"none"、"small"、"medium"、"large"、"extraLarge"、"padding"

id

与项关联的唯一标识符。

类型：string
必需：否

isVisible

如果 false，将从可视化树中删除此项。

类型：boolean
版本：1.2
必需：否，默认值： true

需要

一系列键/值对，说明项目所需功能及其相应的最低版本。当某个功能缺失或版本不够时，将触发降级。

类型：Dictionary<string>
版本：1.2
必需：否

Last updated on 2025-12-09

TextBlock 元素

TextBlock

TextBlock 属性

继承的属性

Example

基本 TextBlock 示例 （JSON）

属性

文本消息

color

颜色示例 （JSON）

字体类型

FontType 示例 （JSON）

horizontalAlignment

HorizontalAlignment 示例 （JSON）

isSubtle

isSubtle 示例 （JSON）