AtomUI/docs/Desktop.Controls/Card/CardAPI.md

Card API 参考

命名空间

namespace AtomUI.Desktop.Controls;

AXAML 命名空间前缀：atom（xmlns:atom="https://atomui.net"）

---

枚举类型

CardStyleVariant

卡片风格变体枚举，定义卡片的视觉风格。

值	说明
Outlined	有边框风格（默认），适用于白色/浅色背景
Borderless	无边框风格，使用阴影代替，适用于灰色/有色背景

CardContentType（内部枚举）

卡片内容类型，根据 Content 的实际类型自动推断，不可外部设置。

值	说明
Default	默认内容类型
Meta	Meta 描述型（Content 为 CardMetaContent）
Grid	网格型（Content 为 CardGridContent）
Tabs	标签页型（Content 为 CardTabsContent）

SizeType（来自 AtomUI.Controls）

尺寸类型枚举。

值	说明
Small	小号
Middle	中号（默认）
Large	大号

---

Card 公共属性（StyledProperty）

属性名	类型	默认值	说明
BoxShadow	BoxShadows	无阴影（Outline）/ BoxShadowsTertiary（Borderless）	卡片阴影效果，悬浮时自动切换为 CardShadows
Extra	object?	null	头部右侧额外区域内容（如 "More" 链接）
ExtraTemplate	IDataTemplate?	null	额外区域数据模板
StyleVariant	CardStyleVariant	Outlined	卡片风格变体（有边框 / 无边框）
SizeType	SizeType	SizeType.Middle	卡片尺寸（共享属性，通过 AddOwner 注册）
IsLoading	bool	false	加载中状态，显示骨架屏占位
IsInnerMode	bool	false	内嵌模式，头部背景变为 ColorFillAlter 以区分嵌套层级
IsHoverable	bool	false	悬浮效果，鼠标悬浮时卡片升起（阴影加深、光标变手形）
Cover	object?	null	封面内容（通常为 Image 控件）
CoverTemplate	IDataTemplate?	null	封面数据模板
IsMotionEnabled	bool	跟随全局 Token（EnableMotion）	是否启用过渡动画（共享属性）

集合属性

属性名	类型	说明
Actions	Avalonia.Controls.Controls	操作区控件集合（CLR 属性，非 StyledProperty），推荐使用 CardActionButton

继承自 HeaderedContentControl 的常用属性

属性名	类型	默认值	说明
Content	object?	null	卡片主体内容
ContentTemplate	IDataTemplate?	null	内容模板
Header	object?	null	卡片标题（设为字符串或控件）
HeaderTemplate	IDataTemplate?	null	标题模板
Background	IBrush?	ColorBgContainer	背景色（由主题控制）
BorderBrush	IBrush?	ColorBorderSecondary	边框颜色（由主题控制）
BorderThickness	Thickness	由 Token BorderThickness 控制	边框粗细
CornerRadius	CornerRadius	由 Token BorderRadiusLG 控制	圆角半径
Padding	Thickness	由 Token 控制	内间距
HorizontalContentAlignment	HorizontalAlignment	Stretch	内容水平对齐
VerticalContentAlignment	VerticalAlignment	Stretch	内容垂直对齐
IsEnabled	bool	true	是否启用

---

伪类（Pseudo-Classes）

Card 支持以下伪类，可在样式选择器中使用：

伪类	常量	触发条件
:headerless	CardPseudoClass.Headerless	Header、HeaderTemplate、Extra、ExtraTemplate 均为 null

继承的标准伪类

伪类	触发条件
:pointerover	鼠标悬浮（配合 IsHoverable 使用时触发阴影切换）
:disabled	IsEnabled == false
:focus	获得焦点

---

实现的接口

ISizeTypeAware

public SizeType SizeType { get; set; }

支持 Small / Middle / Large 三种尺寸，影响头部高度、字号、内容内边距。

IMotionAwareControl

public bool IsMotionEnabled { get; set; }

控制 BoxShadow 过渡动画是否启用。

---

CardMetaContent API

结构化 Meta 内容控件，继承自 HeaderedContentControl。用于在卡片中展示「头像 + 标题 + 描述」的结构化信息。

namespace AtomUI.Desktop.Controls;
public class CardMetaContent : HeaderedContentControl

公共属性

属性名	类型	默认值	说明
Avatar	Avatar?	null	头像控件
Header（继承）	object?	null	标题内容（显示为粗体、大字号）
HeaderTemplate（继承）	IDataTemplate?	null	标题模板
Content（继承）	object?	null	描述内容（显示为描述色）
ContentTemplate（继承）	IDataTemplate?	null	描述模板

模板结构

DockPanel (HorizontalSpacing=Spacing)
├── ContentPresenter#AvatarContentPresenter (Dock=Left)  ← 头像
└── DockPanel (VerticalSpacing=SpacingXS)
    ├── ContentPresenter#TitleContentPresenter (Dock=Top) ← 标题（粗体、FontSizeLG）
    └── ContentPresenter#DescriptionContentPresenter      ← 描述（ColorTextDescription）

---

CardTabsContent API

内嵌标签页内容控件，继承自 TemplatedControl。将 TabControl 嵌入卡片中，实现同一卡片内切换多个内容面板。

namespace AtomUI.Desktop.Controls;
public class CardTabsContent : TemplatedControl

公共属性

属性名	类型	默认值	说明
TabBarExtraContent	object?	null	标签栏右侧额外内容（如 "More" 按钮）
TabBarExtraContentTemplate	IDataTemplate?	null	标签栏额外内容模板
TabItemsSource	IEnumerable?	null	标签页数据源（用于数据绑定场景）
TabItemTemplate	IDataTemplate?	null	标签页项模板

集合属性

属性名	类型	说明
Items	Controls（标记 [Content]）	标签页子项集合，直接添加 TabItem 控件

---

CardGridContent API

网格布局内容控件，继承自 ItemsControl。将内容以等分网格方式布局，每个格子可独立交互。

namespace AtomUI.Desktop.Controls;
public class CardGridContent : ItemsControl

公共属性

属性名	类型	默认值	说明
ColumnDefinitions	ColumnDefinitions	空	Grid 列定义（语法同 Avalonia Grid）
RowDefinitions	RowDefinitions	空	Grid 行定义
IsHoverable	bool	true	网格项是否支持悬浮效果

---

CardGridItem API

网格单元格控件，继承自 ContentControl。作为 CardGridContent 的子项使用。

namespace AtomUI.Desktop.Controls;
public class CardGridItem : ContentControl

公共属性

属性名	类型	默认值	说明
BoxShadow	BoxShadows	CardGridItemShadows（Token）	单元格边框阴影（模拟分割线效果）
Row	int	0	在 Grid 中的行索引
Column	int	0	在 Grid 中的列索引
RowSpan	int	0	跨行数
ColumnSpan	int	0	跨列数
IsHoverable	bool	true	鼠标悬浮时是否显示阴影升起效果
SizeType	SizeType	SizeType.Middle	尺寸（影响单元格内边距）
Content（继承）	object?	null	单元格内容

---

CardActionButton API

卡片操作区按钮，继承自 IconButton。无额外属性定义，主题中自定义了默认样式。

namespace AtomUI.Desktop.Controls;
public class CardActionButton : IconButton

主题默认样式

属性	值	说明
HorizontalAlignment	Stretch	水平撑满操作区格子
VerticalAlignment	Stretch	垂直撑满
IconWidth / IconHeight	CardActionsIconSize	图标大小由 Token 控制
IconBrush	ColorIcon	正常态图标颜色
IconBrush（:pointerover）	ColorPrimary	悬浮态图标变为主色