AtomUI/docs/Desktop.Controls/Window/WindowAPI.md

Window API 参考

命名空间

namespace AtomUI.Desktop.Controls;

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

---

枚举类型

OsType（来自 AtomUI）

操作系统类型枚举。

值	说明
Windows	Windows 平台
macOS	macOS 平台
Linux	Linux 平台
Android	Android 平台
iOS	iOS 平台
FreeBSD	FreeBSD 平台
Unknown	未知平台

MediaBreakPoint（来自 AtomUI.Controls）

媒体断点枚举，定义响应式断点阈值。

值	数值	对应宽度
ExtraSmall	0	≤ 575px
Small	576	≥ 576px
Medium	768	≥ 768px
Large	992	≥ 992px（默认值）
ExtraLarge	1200	≥ 1200px
ExtraExtraLarge	1600	≥ 1600px

WindowState（来自 Avalonia.Controls）

窗口状态枚举。

值	说明
Normal	正常状态
Minimized	最小化
Maximized	最大化
FullScreen	全屏

---

Window 公共属性（StyledProperty）

标题栏相关

属性名	类型	默认值	说明
IsTitleBarVisible	bool	true	是否显示自定义标题栏
TitleFontSize	double	13	标题文字字号
TitleFontWeight	FontWeight	FontWeight.Bold	标题文字字重
Logo	Control?	null	标题栏 Logo 控件（通常放置应用图标）
TitleBarContextMenu	ContextMenu?	null	标题栏右键菜单

标题按钮配置

属性名	类型	默认值	说明
IsFullScreenCaptionButtonEnabled	bool	false	是否显示全屏按钮
IsPinCaptionButtonEnabled	bool	false	是否显示置顶（Pin）按钮
IsCloseCaptionButtonEnabled	bool	true	是否启用关闭按钮（macOS 下通过原生 API 控制）

窗口框架层（Window Frame Layer）

属性名	类型	默认值	说明
WindowFrameLayer	object?	null	窗口级框架背景内容（覆盖整个窗口区域）
WindowFrameLayerTemplate	IDataTemplate?	null	窗口框架背景内容模板
WindowFrameLayerOpacity	double	1.0	窗口框架背景层不透明度

内容框架层（Content Frame Layer）

属性名	类型	默认值	说明
ContentFrameLayer	object?	null	内容区域框架背景内容
ContentFrameLayerTemplate	IDataTemplate?	null	内容框架背景内容模板
ContentFrameLayerOpacity	double	1.0	内容框架背景层不透明度
ContentFrameBackground	IBrush?	null	内容框架背景画刷

标题栏框架层（TitleBar Frame Layer）

属性名	类型	默认值	说明
TitleBarFrameLayer	object?	null	标题栏框架背景内容
TitleBarFrameLayerTemplate	IDataTemplate?	null	标题栏框架背景内容模板
TitleBarFrameLayerOpacity	double	1.0	标题栏框架背景层不透明度
TitleBarFrameBackground	IBrush?	null	标题栏框架背景画刷

窗口行为

属性名	类型	默认值	说明
MaxWidthScreenRatio	double	double.NaN	窗口最大宽度占屏幕工作区的比例（0~1），NaN 表示不限制
MaxHeightScreenRatio	double	double.NaN	窗口最大高度占屏幕工作区的比例（0~1），NaN 表示不限制
IsMoveEnabled	bool	true	是否允许通过标题栏拖拽移动窗口

操作系统感知（来自 IOperationSystemAware）

属性名	类型	默认值	说明
OsType	OsType	OsType.Unknown	当前操作系统类型（构造时自动检测，只读）
OsVersion	Version	-	当前操作系统版本（构造时自动检测，只读）

响应式布局（来自 IMediaBreakAwareControl）

属性名	类型	默认值	说明
MediaBreakPoint	MediaBreakPoint	MediaBreakPoint.Large	当前媒体断点（基于内容区宽度自动计算）

macOS 特有属性

属性名	类型	默认值	说明
MacOSCaptionGroupOffset	Point	(10, 0)	macOS 红绿灯按钮组的偏移量
MacOSCaptionGroupSpacing	double	10.0	macOS 红绿灯按钮之间的间距

注意：MacOSCaptionGroupOffset 和 MacOSCaptionGroupSpacing 标记了 [SupportedOSPlatform("macos")]，仅在 macOS 平台有效。

继承自 Avalonia.Controls.Window 的常用属性

属性名	类型	默认值	说明
Title	string	""	窗口标题文本
Icon	WindowIcon?	null	窗口图标（任务栏/标题栏使用）
Content	object?	null	窗口内容
ContentTemplate	IDataTemplate?	null	内容模板
WindowState	WindowState	Normal	窗口状态
WindowStartupLocation	WindowStartupLocation	Manual	启动位置
CanResize	bool	true	是否允许调整大小
CanMinimize	bool	true	是否允许最小化
CanMaximize	bool	true	是否允许最大化
Topmost	bool	false	是否置顶
ShowInTaskbar	bool	true	是否在任务栏显示
SystemDecorations	SystemDecorations	由主题按平台设置	系统装饰风格
ExtendClientAreaToDecorationsHint	bool	true（主题设置）	客户区扩展到装饰区域
TransparencyLevelHint	WindowTransparencyLevel[]	[Transparent]（主题设置）	透明度级别提示
Background	IBrush?	由 Token 控制	背景色
Foreground	IBrush?	由 Token 控制	前景色
FontSize	double	由 Token 控制	字体大小
FontFamily	FontFamily	由 Token 控制	字体族
CornerRadius	CornerRadius	由 Token 控制	圆角半径
Padding	Thickness	0	内容区内间距
Width / Height	double	NaN	窗口宽度/高度
MinWidth / MinHeight	double	0	最小宽度/高度
MaxWidth / MaxHeight	double	+∞	最大宽度/高度（可由 MaxWidthScreenRatio 自动约束）

---

事件

事件名	类型	说明
MediaBreakPointChanged	EventHandler<MediaBreakPointChangedEventArgs>	媒体断点变化时触发

继承自 Avalonia.Controls.Window 的常用事件

事件名	类型	说明
Opened	EventHandler	窗口打开时触发
Closing	EventHandler<WindowClosingEventArgs>	窗口即将关闭时触发（可取消）
Closed	EventHandler	窗口关闭后触发
ScalingChanged	EventHandler	DPI 缩放比变化时触发

---

静态方法

方法签名	返回类型	说明
Window.GetMainWindow()	Window?	获取应用程序主窗口（从 IClassicDesktopStyleApplicationLifetime 获取）

---

扩展方法（WindowExtensions）

WindowExtensions 提供以下公共扩展方法：

方法签名	返回类型	说明
window.GetHostScreen()	Screen?	获取窗口所在的屏幕对象
window.CenterOnScreen()	void	将窗口居中到当前所在屏幕
window.CenterOnScreen(Screen?)	void	将窗口居中到指定屏幕
window.ConstrainMaxSizeToScreenRatio(double, double)	void	按屏幕工作区比例约束窗口的 MaxWidth / MaxHeight

---

ReactiveWindow<TViewModel> 专属属性

属性名	类型	默认值	说明
ViewModel	TViewModel?	null	ViewModel 实例，与 DataContext 自动双向同步

ReactiveWindow<TViewModel> 实现 IViewFor<TViewModel> 接口。当 DataContext 变化时自动更新 ViewModel，反之亦然。如果 TViewModel 实现了 IActivatableViewModel，窗口显示时自动激活 ViewModel 的 WhenActivated 生命周期。

---

实现的接口

IOperationSystemAware

public OsType OsType { get; }       // 当前操作系统类型
public Version OsVersion { get; }   // 当前操作系统版本

Window 构造时自动调用 this.ConfigureOsType() 检测平台，后续可在样式选择器中通过 [OsType=Windows]、[OsType=Linux]、[OsType=macOS] 进行平台判断。

IMediaBreakAwareControl

public MediaBreakPoint MediaBreakPoint { get; }
public event EventHandler<MediaBreakPointChangedEventArgs>? MediaBreakPointChanged;

提供内容区域宽度的响应式断点检测。MediaBreakPoint 由模板内的 WindowMediaQueryIndicator 通过 Container Query 自动更新。

IDisposable

public void Dispose();

窗口关闭时（OnClosed）自动调用，清理 ScalingChanged 等事件订阅，避免内存泄漏。