AtomUI/docs/Controls.Shared/MediaQuery/Overview.md

AtomUI 媒体查询（Media Query）系统

本文档描述 AtomUI 响应式布局的核心架构 —— 媒体查询系统（Media Query System）的设计原理、实现机制及开发者使用指南。

---

文档索引

文档	内容
架构设计	系统总体架构、断点检测机制、数据流与核心类型说明
开发者指南	面向控件开发者的使用指南，包含响应式 Grid、Form、Descriptions 等完整示例

---

概述

AtomUI 的媒体查询系统是一套 基于容器宽度的响应式断点机制，完整复现了 Ant Design 5.0 栅格系统 的六级响应式断点策略。它构建在 Avalonia 的 Container Query 机制之上，为 AtomUI 控件提供统一的窗口级响应式能力。

设计目标

1. 对齐 Ant Design 5.0：完整实现 xs / sm / md / lg / xl / xxl 六级断点体系，断点阈值与 Ant Design 完全一致。
2. 基于容器查询：利用 Avalonia 原生的 ContainerQuery + Container.Sizing 机制实现宽度检测，而非自行监听窗口尺寸变化。
3. 统一事件分发：通过 Window 集中管理断点状态，下游控件通过 IMediaBreakAwareControl 接口订阅断点变更事件。
4. 声明式 AXAML 友好：所有响应式数据类型（GridColSpanInfo、GridGutterInfo、MediaBreakGridLength、DescriptionsMediaBreakInfo）均提供 TypeConverter，支持在 AXAML 中以字符串格式直接配置。

断点阈值

断点名称	缩写	最小宽度 (px)	典型设备
ExtraSmall	xs	0	手机竖屏
Small	sm	576	手机横屏
Medium	md	768	平板竖屏
Large	lg	992	平板横屏 / 小桌面
ExtraLarge	xl	1200	标准桌面
ExtraExtraLarge	xxl	1600	大屏桌面

这些阈值定义在 MediaBreakPoint 枚举中，枚举的整数值即为该断点的最小像素宽度。

与 CSS 媒体查询的关系

概念	CSS	AtomUI
检测目标	视口（viewport）	Window 内容区域（ContentFrame）
检测机制	@media (min-width: ...)	Avalonia ContainerQuery + Container.Sizing
断点传播	CSS 变量 / JS 事件	IMediaBreakAwareControl.MediaBreakPointChanged 事件
响应式属性	CSS grid-template-columns 等	GridColSpanInfo、GridGutterInfo、MediaBreakGridLength 等 C# record 类型