AtomUI/docs/Desktop.Controls/Dialog/DialogAPI.md

Dialog API 参考

命名空间

namespace AtomUI.Desktop.Controls;

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

---

枚举类型

DialogHostType

对话框宿主类型，决定对话框的渲染方式。

值	说明
Overlay	在当前窗口的 Overlay 层中渲染（默认）
Window	在独立的原生窗口中渲染

DialogHorizontalAnchor

对话框水平起始位置锚点。

值	说明
Left	靠左对齐
Center	水平居中
Right	靠右对齐
Custom	自定义（使用 HorizontalOffset）

DialogVerticalAnchor

对话框垂直起始位置锚点。

值	说明
Top	靠顶对齐
Center	垂直居中
Bottom	靠底对齐
Custom	自定义（使用 VerticalOffset）

DialogStandardButton（Flags 枚举）

标准按钮标记，可通过位运算或逗号组合。

值	角色	说明
NoButton	—	无按钮
Ok	AcceptRole	"确定"按钮
Open	AcceptRole	"打开"按钮
Save	AcceptRole	"保存"按钮
Cancel	RejectRole	"取消"按钮
Close	RejectRole	"关闭"按钮
Discard	DestructiveRole	"放弃"按钮
Apply	ApplyRole	"应用"按钮
Reset	ResetRole	"重置"按钮
Reload	ResetRole	"重新加载"按钮
RestoreDefaults	ResetRole	"恢复默认"按钮
Help	HelpRole	"帮助"按钮
SaveAll	AcceptRole	"全部保存"按钮
Yes	YesRole	"是"按钮
YesToAll	YesRole	"全部是"按钮
No	NoRole	"否"按钮
NoToAll	NoRole	"全部否"按钮
Abort	RejectRole	"中止"按钮
Retry	AcceptRole	"重试"按钮
Ignore	AcceptRole	"忽略"按钮

DialogButtonRole

按钮角色，决定点击后的对话框行为。

值	说明
AcceptRole	接受角色（点击后触发 Accept）
RejectRole	拒绝角色（点击后触发 Reject）
DestructiveRole	破坏性操作角色
ActionRole	动作角色（不自动关闭对话框）
HelpRole	帮助角色
YesRole	"是"角色（点击后触发 Accept）
NoRole	"否"角色（点击后触发 Reject）
ApplyRole	应用角色（点击后触发 Accept）
ResetRole	重置角色（点击后触发 Accept）
CustomRole	自定义角色

DialogCode

对话框结果代码。

值	说明
Accepted	对话框被接受
Rejected	对话框被拒绝

---

公共属性（StyledProperty）

属性名	类型	默认值	说明
Title	string?	null	对话框标题
TitleIcon	PathIcon?	null	标题栏图标
Content	object?	null	对话框内容（支持任意控件），标记 [Content] 可在 AXAML 中直接作为子元素
ContentTemplate	IDataTemplate?	null	内容数据模板
IsOpen	bool	false	对话框是否打开。设置为 true 时自动调用 OpenAsync()，设置为 false 时触发 Done(Result)
IsModal	bool	true	是否为模态对话框。模态时 OpenAsync() 在关闭后才完成 Task；非模态时打开后立即完成
IsClosable	bool	true	是否显示关闭按钮
IsResizable	bool	false	是否可调整大小
IsMaximizable	bool	false	是否可最大化
IsMinimizable	bool	true	是否可最小化（仅 DialogHostType.Window 宿主有效；模态对话框自动禁用）
IsDragMovable	bool	false	是否可拖拽移动
IsLightDismissEnabled	bool	false	点击遮罩/外部区域是否关闭（仅 Overlay 宿主有效）
IsLoading	bool	false	整体加载状态，内容区域显示加载遮罩
IsConfirmLoading	bool	false	确认加载状态。为 true 时阻止所有关闭请求（NotifyClose 直接返回），防止用户在异步操作完成前关闭
IsFooterVisible	bool	true	是否显示底部按钮区域
DialogHostType	DialogHostType	Overlay	宿主类型
StandardButtons	DialogStandardButtons	NoButton	标准按钮配置（通过 AddOwner 从 DialogButtonBox 共享）
DefaultStandardButton	DialogStandardButton	NoButton	默认确认按钮（视觉高亮，支持 Enter 键触发）
EscapeStandardButton	DialogStandardButton	NoButton	Escape 键触发的按钮
HorizontalStartupLocation	DialogHorizontalAnchor	Custom	水平起始位置锚点
VerticalStartupLocation	DialogVerticalAnchor	Custom	垂直起始位置锚点
HorizontalOffset	Dimension?	null	水平偏移（像素或百分比），当 HorizontalStartupLocation == Custom 时生效
VerticalOffset	Dimension?	null	垂直偏移（像素或百分比），当 VerticalStartupLocation == Custom 时生效
PlacementTarget	Control?	null	定位参考控件。未设置时自动查找逻辑父控件
PlacementCallback	CustomDialogPlacementCallback?	null	自定义定位回调
OverlayDismissEventPassThrough	bool	false	遮罩关闭时是否将指针事件穿透给下层控件
OverlayInputPassThroughElement	IInputElement?	null	输入穿透元素
InheritsTransform	bool	false	是否继承父元素变换（缩放等）
Topmost	bool	false	是否置顶
Result	object?	null	对话框结果值。Accept() 设为 DialogCode.Accepted，Reject() 设为 DialogCode.Rejected，Done(result) 设为自定义值
IsMotionEnabled	bool	跟随全局 Token	是否启用打开/关闭动画（共享属性，通过 AddOwner 注册）

---

只读属性

属性名	类型	说明
Host	IDialogHost?	当前宿主实例（对话框打开后可访问）
IsPointerOverDialog	bool	指针是否位于对话框宿主之上

---

公共集合与回调

属性名	类型	说明
CustomButtons	AvaloniaList<DialogButton>	自定义按钮集合。对话框打开后修改此集合会实时同步到宿主
ButtonsConfigure	Action<IReadOnlyList<DialogButton>>?	按钮创建后的配置回调，可用于统一修改按钮属性（如禁用全部按钮）
DependencyResolver	IAvaloniaDependencyResolver?	Avalonia 依赖注入解析器

---

事件

事件名	类型	说明
Opened	EventHandler?	对话框打开后触发
Closing	EventHandler<CancelEventArgs>?	关闭前触发，设置 Cancel = true 可阻止关闭
Closed	EventHandler?	关闭后触发（宿主清理完成后）
Accepted	EventHandler?	Result 为 DialogCode.Accepted 时触发
Rejected	EventHandler?	Result 为 DialogCode.Rejected 时触发
Finished	EventHandler<DialogFinishedEventArgs>?	对话框完成时触发（在 Accepted/Rejected 之后），包含 Result
ButtonClicked	EventHandler<DialogButtonClickedEventArgs>?	底部按钮被点击时触发。设置 Handled = true 可阻止默认的 Accept/Reject 行为，常用于异步关闭场景

---

公共方法

方法	返回值	说明
Open()	object?	同步打开，创建新的消息循环等待对话框关闭。返回 Result
OpenAsync()	Task	异步打开。模态时 Task 在关闭后完成（可 await 后读取 Result）；非模态时打开后立即完成
Accept()	void	设置 Result = DialogCode.Accepted 并关闭
Reject()	void	设置 Result = DialogCode.Rejected 并关闭
Done(object?)	void	设置自定义 Result 并关闭
Done()	void	直接关闭（不修改 Result）
IsInsideDialog(Visual)	bool	判断指定的可视元素是否位于当前对话框宿主内部

---

静态方法

同步方法

方法签名	返回值	说明
ShowDialog<TView, TViewModel>(TViewModel?, DialogOptions?, TopLevel?)	object?	同步打开（泛型视图 + ViewModel）
ShowDialogModal<TView, TViewModel>(TViewModel?, DialogOptions?, TopLevel?)	object?	同步模态打开（泛型视图 + ViewModel）
ShowDialog(Control, object?, DialogOptions?, TopLevel?)	object?	同步打开（直接传入内容控件）
ShowDialogModal(Control, object?, DialogOptions?, TopLevel?)	object?	同步模态打开（直接传入内容控件）

异步方法

方法签名	返回值	说明
ShowDialogAsync<TView, TViewModel>(TViewModel?, DialogOptions?, Action<IDialogActionResult>?, TopLevel?)	Task	异步打开。非模态时通过 closed 回调获取结果
ShowDialogModalAsync<TView, TViewModel>(TViewModel?, DialogOptions?, TopLevel?)	Task<object?>	异步模态打开，await 后直接获取结果
ShowDialogAsync(Control, object?, DialogOptions?, Action<IDialogActionResult>?, TopLevel?)	Task	异步打开（内容控件版本）。通过 closed 回调获取结果
ShowDialogModalAsync(Control, object?, DialogOptions?, TopLevel?)	Task<object?>	异步模态打开（内容控件版本）

提示：非模态异步方法 ShowDialogAsync 提供 Action<IDialogActionResult>? closed 回调参数，在对话框关闭时调用，可通过 IDialogActionResult.Result 读取结果。模态异步方法 ShowDialogModalAsync 的 Task 在关闭后完成，可直接 await 获取返回值。

---

配置类

DialogOptions

DialogOptions 是一个 record 类型，用于在静态 API 中配置对话框参数。

public record DialogOptions
{
    public string? Title { get; init; }
    public PathIcon? TitleIcon { get; init; }
    public bool IsLightDismissEnabled { get; init; }       // 仅 Overlay 宿主有效
    public bool IsResizable { get; init; }
    public bool IsClosable { get; init; } = true;
    public bool IsMaximizable { get; init; }
    public bool IsMinimizable { get; init; } = true;       // 仅 Window 宿主有效
    public bool IsDragMovable { get; init; }
    public bool IsFooterVisible { get; init; } = true;
    public Control? PlacementTarget { get; init; }
    public Dimension? HorizontalOffset { get; init; }
    public Dimension? VerticalOffset { get; init; }
    public DialogHostType DialogHostType { get; init; } = DialogHostType.Overlay;
    public DialogStandardButtons StandardButtons { get; init; } = DialogStandardButton.NoButton;
    public DialogStandardButton DefaultStandardButton { get; init; }
    public DialogHorizontalAnchor HorizontalStartupLocation { get; init; } = DialogHorizontalAnchor.Custom;
    public DialogVerticalAnchor VerticalStartupLocation { get; init; } = DialogVerticalAnchor.Custom;
    public double Width { get; init; } = double.NaN;
    public double Height { get; init; } = double.NaN;
    public double MinWidth { get; init; } = 0d;
    public double MinHeight { get; init; } = 0d;
    public double MaxWidth { get; init; } = double.PositiveInfinity;
    public double MaxHeight { get; init; } = double.PositiveInfinity;
}

---

事件参数类

DialogButtonClickedEventArgs

public class DialogButtonClickedEventArgs : EventArgs
{
    public DialogButton SourceButton { get; }   // 被点击的按钮实例
    public bool Handled { get; set; }           // 设为 true 可阻止默认 Accept/Reject 行为
}

DialogFinishedEventArgs

public class DialogFinishedEventArgs : EventArgs
{
    public object? Result { get; }              // 对话框结果值
}

---

关键接口

IDialog

public interface IDialog
{
    string? Title { get; set; }
    object? Result { get; set; }
    event EventHandler? Closed;
    event EventHandler? Opened;
    event EventHandler<CancelEventArgs>? Closing;
    event EventHandler? Accepted;
    event EventHandler? Rejected;
    event EventHandler<DialogFinishedEventArgs>? Finished;
    event EventHandler<DialogButtonClickedEventArgs>? ButtonClicked;
    void Accept();
    void Reject();
    void Done(object? result);
    void Done();
}

IDialogAwareDataContext

ViewModel 实现此接口后，当被设置为 Dialog 的 DataContext 时，会自动收到通知：

public interface IDialogAwareDataContext
{
    void NotifyAttachedToDialog(IDialog dialog);    // DataContext 被关联到 Dialog 时调用
    void NotifyDetachedFromDialog() {}              // DataContext 被解除关联时调用（有默认空实现）
    void NotifyClosed() {}                          // Dialog 关闭后调用（有默认空实现）
}

IDialogActionResult

非模态异步对话框关闭回调中的结果接口：

public interface IDialogActionResult
{
    object? Result { get; }
}

DialogButton

继承自 Button，用作对话框底部按钮。

属性名	类型	说明
StandardButtonType	DialogStandardButton?	对应的标准按钮类型
Role	DialogButtonRole	按钮角色（默认 CustomRole）
IsDefaultConfirmButton	bool	是否为默认确认按钮（视觉高亮）
IsDefaultEscapeButton	bool	是否为默认 Escape 按钮