裝飾項概觀

發行項
10/18/2023

裝飾項是一種特殊的類型 FrameworkElement ，用來為使用者提供視覺提示。除了其他用法，裝飾項還可用來將功能控點加入項目，或提供控制項的狀態資訊。

關於裝飾項

Adorner是系結至的 UIElement 自訂 FrameworkElement 。裝飾項會在中 AdornerLayer 轉譯，這是一律位於裝飾專案或裝飾專案集合之上的轉譯表面。裝飾項的轉譯與裝飾項系結的 UIElement 呈現無關。裝飾項通常相對於所系結的元素，使用位於裝飾元素左上角的標準 2D 座標原點。

裝飾項的常見應用包括︰

將功能控制碼新增至 UIElement ，讓使用者以某種方式操作專案（調整大小、旋轉、重新置放等）。
提供視覺化回應以表示各種狀態，或回應各種事件。
在上 UIElement 重迭視覺裝飾。
以視覺方式遮罩或覆寫部分或全部 UIElement 。

Windows Presentation Foundation （WPF）提供裝飾視覺元素的基本架構。下表列出在裝飾物件時所使用的主要類型，及其用途。數個使用範例如下：

類別	描述
Adorner	抽象基底類別，所有具體裝飾項實作都繼承自該類別。
AdornerLayer	代表一個或多個裝飾項目的裝飾項轉譯層的類別。
AdornerDecorator	可讓裝飾項層與項目集合相關聯的類別。

實作自訂裝飾項

Windows Presentation Foundation （WPF）所提供的裝飾項架構主要是為了支援建立自訂裝飾項。藉由實作繼承自抽象 Adorner 類的類別來建立自訂裝飾項。

注意

的 Adorner 父代是 AdornerLayer 呈現的 Adorner ，而不是裝飾的專案。

下列範例顯示一個實作簡單裝飾項的類別。範例裝飾項只會使用圓形裝飾的 UIElement 角落。

// Adorners must subclass the abstract base class Adorner.
public class SimpleCircleAdorner : Adorner
{
  // Be sure to call the base class constructor.
  public SimpleCircleAdorner(UIElement adornedElement)
    : base(adornedElement)
  {
  }

  // A common way to implement an adorner's rendering behavior is to override the OnRender
  // method, which is called by the layout system as part of a rendering pass.
  protected override void OnRender(DrawingContext drawingContext)
  {
    Rect adornedElementRect = new Rect(this.AdornedElement.DesiredSize);

    // Some arbitrary drawing implements.
    SolidColorBrush renderBrush = new SolidColorBrush(Colors.Green);
    renderBrush.Opacity = 0.2;
    Pen renderPen = new Pen(new SolidColorBrush(Colors.Navy), 1.5);
    double renderRadius = 5.0;

    // Draw a circle at each corner.
    drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.TopLeft, renderRadius, renderRadius);
    drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.TopRight, renderRadius, renderRadius);
    drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.BottomLeft, renderRadius, renderRadius);
    drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.BottomRight, renderRadius, renderRadius);
  }
}

Public Class SimpleCircleAdorner
    Inherits Adorner
    Sub New(ByVal adornedElement As UIElement)
        MyBase.New(adornedElement)
    End Sub

    Protected Overrides Sub OnRender(ByVal drawingContext As System.Windows.Media.DrawingContext)
        MyBase.OnRender(drawingContext)
        Dim adornedElementRect As New Rect(AdornedElement.DesiredSize)
        Dim renderBrush As New SolidColorBrush(Colors.Green)
        renderBrush.Opacity = 0.2
        Dim renderPen As New Pen(New SolidColorBrush(Colors.Navy), 1.5)
        Dim renderRadius As Double
        renderRadius = 5.0

        'Draw a circle at each corner.
        drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.TopLeft, renderRadius, renderRadius)
        drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.TopRight, renderRadius, renderRadius)
        drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.BottomLeft, renderRadius, renderRadius)
        drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.BottomRight, renderRadius, renderRadius)
    End Sub
End Class

下圖顯示套用至 TextBox 的 SimpleCircleAdorner：

Screenshot that shows an adorned text box.

裝飾項的轉譯行為

請務必注意，裝飾項並不包括任何繼承的轉譯行為。裝飾項實作者必須負責確定裝飾項轉譯器。實作轉譯行為的常見方式是覆寫 OnRender 方法，並使用一或多個 DrawingContext 物件視需要轉譯裝飾項的視覺效果（如上述範例所示）。

注意

放在裝飾項圖層中的任何項目會轉譯在您已設定的其餘任何樣式之上。換句話說，裝飾項永遠是以視覺化方式在最上面，而且無法使用疊置順序覆寫。

事件和點擊測試

裝飾項會像任何其他 FrameworkElement 一樣接收輸入事件。因為裝飾項一律有比裝飾專案更高的 z 順序，所以裝飾項會接收輸入事件（例如 Drop 或 MouseMove ），這些事件可能適用于基礎裝飾專案。裝飾項可以接聽特定的輸入事件，並藉由重新引發事件將它們傳送到基礎的被裝飾項目。

若要在裝飾項下啟用元素的傳遞點擊測試，請將裝飾項上的點擊測試 IsHitTestVisible 屬性設定為 false 。如需點擊測試的詳細資訊，請參閱視覺層中的點擊測試。

裝飾單一的 UIElement

若要將裝飾項系結至特定 UIElement ，請遵循下列步驟：

呼叫靜態方法 GetAdornerLayer ，以取得 AdornerLayer 要裝飾的 UIElement 物件。 GetAdornerLayer 從指定的 UIElement 開始，逐步執行視覺化樹狀結構，並傳回它找到的第一個裝飾項圖層。 (如果找不到任何裝飾項圖層，方法會傳回 null。)
Add呼叫方法，將裝飾項系結至目標 UIElement 。

下列範例會將 SimpleCircleAdorner （如上所示）系結至 TextBox 名為 myTextBox ：

myAdornerLayer = AdornerLayer.GetAdornerLayer(myTextBox);
myAdornerLayer.Add(new SimpleCircleAdorner(myTextBox));

myAdornerLayer = AdornerLayer.GetAdornerLayer(myTextBox)
myAdornerLayer.Add(New SimpleCircleAdorner(myTextBox))

注意

目前不支援使用 Extensible Application Markup Language （XAML）將裝飾項系結至另一個專案。

裝飾 Panel 的子系

若要將裝飾項系結至的 Panel 子系，請遵循下列步驟：

static呼叫方法 GetAdornerLayer ，為要裝飾其子系的專案尋找裝飾項圖層。
列舉父元素的子系，並呼叫 Add 方法，將裝飾項系結至每個子專案。

下列範例會將 SimpleCircleAdorner （如上所示）系結至具名 myStackPanel 的 StackPanel 子系：

foreach (UIElement toAdorn in myStackPanel.Children)
  myAdornerLayer.Add(new SimpleCircleAdorner(toAdorn));

For Each toAdorn As UIElement In myStackPanel.Children
    myAdornerLayer.Add(New SimpleCircleAdorner(toAdorn))
Next