AtomUI/docs/Desktop.Controls/Grid/GridAPI.md

Grid API 参考

命名空间

namespace AtomUI.Desktop.Controls;  // Row, Col, ColInfo, ColInfoExtension, GridGutter, GridGutterInfo, GridColSpanInfo, GridColSize, RowJustify, RowAlign
namespace AtomUI.Controls;           // MediaBreakPoint, IMediaBreakAwareControl

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

---

枚举类型

RowJustify

主轴对齐方式枚举。支持 TypeConverter，AXAML 中可使用 CSS 风格字符串（如 "space-between"）。

值	CSS 等价	说明
Start	flex-start	左对齐（默认）
Center	center	居中对齐
End	flex-end	右对齐
SpaceBetween	space-between	两端对齐，项之间等间距
SpaceAround	space-around	每项两侧等间距
SpaceEvenly	space-evenly	所有间距完全相等

RowAlign

交叉轴对齐方式枚举。支持 TypeConverter，AXAML 中可使用 "top" / "middle" / "bottom" / "stretch" 字符串。

值	说明
Top	顶部对齐
Middle	垂直居中
Bottom	底部对齐
Stretch	拉伸填满行高（默认）

MediaBreakPoint（来自 AtomUI.Controls）

响应式断点枚举。

值	宽度阈值
ExtraSmall	< 576px
Small	≥ 576px
Medium	≥ 768px
Large	≥ 992px
ExtraLarge	≥ 1200px
ExtraExtraLarge	≥ 1600px

---

Row 公共属性（StyledProperty）

属性名	类型	默认值	说明
Gutter	GridGutter	new GridGutter() (0,0)	列间距（水平 + 垂直），支持 TypeConverter 字符串解析
Justify	RowJustify	Start	主轴对齐方式
Align	RowAlign	Stretch	交叉轴对齐方式
Wrap	bool	true	是否允许列换行（Span 总和超过 24 时）

Row 继承自 Panel，拥有 Panel 的所有属性（Background、Children、ClipToBounds 等）。

---

Col 公共属性（StyledProperty）

属性名	类型	默认值	验证规则	说明
Span	GridColSpanInfo	0	0-24	列占据的栅格数，支持响应式字符串
Offset	int	0	0-24	列向右偏移的栅格数
Order	int	0	任意整数	列的排列顺序
Push	int	0	0-24	列向右视觉位移的栅格数
Pull	int	0	0-24	列向左视觉位移的栅格数
Xs	GridColSize?	null	—	ExtraSmall 断点配置
Sm	GridColSize?	null	—	Small 断点配置
Md	GridColSize?	null	—	Medium 断点配置
Lg	GridColSize?	null	—	Large 断点配置
Xl	GridColSize?	null	—	ExtraLarge 断点配置
Xxl	GridColSize?	null	—	ExtraExtraLarge 断点配置

Col 继承自 ContentControl，拥有 Content、ContentTemplate、HorizontalContentAlignment、VerticalContentAlignment 等属性。

---

数据类型

GridGutter

列间距配置，支持 TypeConverter 从字符串解析。

属性	类型	说明
Horizontal	GridGutterInfo	水平间距配置
Vertical	GridGutterInfo	垂直间距配置

AXAML 字符串格式：

格式	示例	说明
单数字	"16"	水平间距 16，垂直间距 0
两个数字	"16,24"	水平 16，垂直 24
响应式	"xs:8,sm:16,md:24"	按断点设置水平间距
水平+垂直响应式	"xs:8,sm:16;xs:16,sm:24"	用 ; 分隔水平和垂直

构造方法：

签名	说明
GridGutter()	全零间距
GridGutter(GridGutterInfo horizontal, GridGutterInfo vertical)	指定水平和垂直间距

静态方法：

方法	签名	说明
Parse	static GridGutter Parse(string input)	从字符串解析

GridGutterInfo

响应式间距值，每个断点一个 double 值。

属性	类型	说明
ExtraSmall	double	xs 断点间距值
Small	double	sm 断点间距值
Medium	double	md 断点间距值
Large	double	lg 断点间距值
ExtraLarge	double	xl 断点间距值
ExtraExtraLarge	double	xxl 断点间距值

构造方法：

签名	说明
GridGutterInfo()	全零
GridGutterInfo(double value)	所有断点使用同一值
GridGutterInfo(double xs, double sm, double md, double lg, double xl, double xxl)	每个断点独立值

AXAML 字符串格式："xs:8,sm:16,md:24,lg:32,xl:40,xxl:48" 或单数字 "16"

GridColSpanInfo

响应式 Span 值（readonly record struct），每个断点一个 int 值。支持隐式从 int 转换。

属性	类型	说明
ExtraSmall	int	xs 断点 Span 值
Small	int	sm 断点 Span 值
Medium	int	md 断点 Span 值
Large	int	lg 断点 Span 值
ExtraLarge	int	xl 断点 Span 值
ExtraExtraLarge	int	xxl 断点 Span 值

AXAML 字符串格式："xs:24,sm:12,md:8,lg:6" 或单数字 "12"

隐式转换：GridColSpanInfo span = 12;

GridColSize / ColInfo

按断点存储列的完整布局配置。ColInfo 是 GridColSize 的别名（继承），带有 GridColSizeConverter 支持 AXAML 解析。

属性	类型	说明
Span	int?	栅格数（0-24），null 表示不覆盖
Offset	int?	偏移栅格数（0-24），null 表示不覆盖
Order	int?	排列顺序，null 表示不覆盖
Push	int?	向右视觉位移（0-24），null 表示不覆盖
Pull	int?	向左视觉位移（0-24），null 表示不覆盖

AXAML 字符串格式：

• 纯数字："12" → Span = 12
• 键值对："span:12,offset:4,order:2" → Span = 12, Offset = 4, Order = 2

ColInfoExtension（MarkupExtension）

AXAML MarkupExtension，用于在属性内联中构造 GridColSize 对象。

属性	类型	说明
Span	int?	栅格数（0-24）
Offset	int?	偏移栅格数（0-24）
Order	int?	排列顺序
Push	int?	向右视觉位移（0-24）
Pull	int?	向左视觉位移（0-24）

使用方式：

<atom:Col Sm="{atom:ColInfo Span=12, Order=2}" />

---

TypeConverter 汇总

类型	TypeConverter	AXAML 示例
GridGutter	GridGutterConverter	Gutter="16,24"
GridGutterInfo	内部使用 Parse()	—
GridColSpanInfo	GridColSpanInfoConverter	Span="xs:24,sm:12,md:8"
GridColSize / ColInfo	GridColSizeConverter	Xs="span:12,offset:4" 或 Xs="12"
RowJustify	RowJustifyConverter	Justify="space-between"
RowAlign	RowAlignConverter	Align="middle"