攻克Avalonia Dock布局中WebView等原生控件无法停靠的难题

Avalonia 是一款适用于开发跨平台桌面应用的核心框架，也是当前国内推动信息技术应用创新的重要技术方案之一。基于 Avalonia 开发的应用程序能够高效、稳定地兼容并运行于主流的国产桌面操作系统之上。

Avalonia 拥有活跃的社区和丰富的生态系统，其主流的布局方案 Dock Layout 在开发中应用广泛。然而，当布局中包含 WebView(https://github.com/OutSystems/WebView) 这类依赖原生窗口句柄的控件时，便会遇到一个显著挑战：拖拽至目标区域时，停靠指示器（）无法正常显示，导致整个停靠功能失效。本文将深入分析此问题根源，并提供一套稳定可靠的解决方案。

问题根源：

通过源码调试与分析发现：停靠指示器（Dock Adorner / Indicator）的创建流程是完全正常的，相关代码已成功执行，对象也已正确实例化。问题的真正原因在于层级（Z-Order）机制：Avalonia 的 Dock 系统通过 Adorner Layer层绘制停靠指示器，而 WebView 等控件本质上是原生窗口句柄（HWND），它们始终位于 Avalonia 托管可视化树之上。

DockManager

└─ AdornerLayer

└─ DockTargetIndicators

因此，即使指示器已存在，也会被 WebView 窗口完全遮挡，导致用户"看不到停靠提示"，进而误以为 Dock 功能失效。

解决方案：

既然问题的本质是原生窗口遮挡托管层，那么最直接的解决方式就是：将停靠指示器从 AdornerLayer 移至更高优先级的 Overlay 层，例如 Popup、TopLevel Overlay等系统级顶层容器。

DockManager

└─ OverlayLayer (Popup / TopLevel)

└─ DockTargetIndicators

实现代码：

核心是将原 DockTargetControl迁移至一个 Popup容器中，并通过以下配置确保其始终显示在所有原生窗口之上：

cs 复制代码

//Old code
//Adorner = new DockTarget
//{
//    [AdornerLayer.AdornedElementProperty] = visual,
//};
var popup = new Popup()
{
	IsOpen = true,
	Placement = PlacementMode.Center,
	Width = visual.Bounds.Width,
	Height = visual.Bounds.Height,
	Child = new DockTarget
	{
		[AdornerLayer.AdornedElementProperty] = visual,
	}
};
Adorner = popup;

受影响的地方，原来获取DockTarget的地方，修改为从Popup Child里获取：

cs 复制代码

//Old code
//if (_adornerHelper.Adorner is DockTarget target)
//{
//    operation = target.GetDockOperation(point, relativeTo, dragAction, Validate);
//}
if (_adornerHelper.Adorner is Popup popup && popup.Child is DockTarget target)
{
	operation = target.GetDockOperation(point, relativeTo, dragAction, Validate);
}