mirror of
https://github.com/AtomUI/AtomUI.git
synced 2026-10-19 23:30:44 +08:00
chinboy
236 lines
8.8 KiB
Markdown
236 lines
8.8 KiB
Markdown
# Window API 参考
|
||
|
||
## 命名空间
|
||
|
||
```csharp
|
||
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
|
||
|
||
```csharp
|
||
public OsType OsType { get; } // 当前操作系统类型
|
||
public Version OsVersion { get; } // 当前操作系统版本
|
||
```
|
||
|
||
Window 构造时自动调用 `this.ConfigureOsType()` 检测平台，后续可在样式选择器中通过 `[OsType=Windows]`、`[OsType=Linux]`、`[OsType=macOS]` 进行平台判断。
|
||
|
||
### IMediaBreakAwareControl
|
||
|
||
```csharp
|
||
public MediaBreakPoint MediaBreakPoint { get; }
|
||
public event EventHandler<MediaBreakPointChangedEventArgs>? MediaBreakPointChanged;
|
||
```
|
||
|
||
提供内容区域宽度的响应式断点检测。`MediaBreakPoint` 由模板内的 `WindowMediaQueryIndicator` 通过 Container Query 自动更新。
|
||
|
||
### IDisposable
|
||
|
||
```csharp
|
||
public void Dispose();
|
||
```
|
||
|
||
窗口关闭时（`OnClosed`）自动调用，清理 `ScalingChanged` 等事件订阅，避免内存泄漏。
|