裝飾項概觀

發行項
08/12/2011

裝飾項是特殊類型的 FrameworkElement，可用來為使用者提供視覺化提示。至於其他的用途，裝飾項還可用於將功能控點加入至項目，或提供有關控制項的狀態資訊。

這個主題包含下列章節。

關於裝飾項
實作自訂裝飾項
裝飾項的呈現行為
事件和點擊測試
裝飾單一 UIElement
裝飾面板的子系
相關主題

關於裝飾項

Adorner 是已繫結至 UIElement 的自訂 FrameworkElement。裝飾項會呈現於 AdornerLayer 中，這是個永遠位於已裝飾項目或已裝飾項目集合最上面的呈現介面。裝飾項的呈現與裝飾項所繫結之 UIElement 的呈現無關。裝飾項的定位通常相對於它所繫結的項目，並採用位於已裝飾項目左上方的標準 2-D 座標原點。

裝飾項的一般應用包含：

將功能控點加入至 UIElement，讓使用者能夠以某種方式操作項目 (調整大小、旋轉、重新調整位置等)。
提供視覺化回應以表示各種狀態，或回應各種事件。
在 UIElement 上覆疊視覺化裝飾。
以視覺化方式遮蔽或覆寫部分或所有的 UIElement。

Windows Presentation Foundation (WPF) 會提供可供裝飾視覺化項目的基本架構。下表列出在裝飾物件時使用的主要類型及其目的。以下是數個使用方式的範例。

Adorner	抽象基底類別，所有具象裝飾項實作都繼承自這個類別。
AdornerLayer	一個類別，表示一個或多個已裝飾項目之裝飾項的轉譯層。
AdornerDecorator	一個類別，能夠讓裝飾項層與項目集合產生關聯。

實作自訂裝飾項

Windows Presentation Foundation (WPF) 所提供的裝飾項架構主要用於支援自訂裝飾項的建立。就由實作繼承自抽象 Adorner 類別的類別，即可建立自訂裝飾項。

注意事項
Adorner 的父代 (Parent) 是會呈現 Adorner 的 AdornerLayer，而不是要裝飾的項目。

下列範例顯示了實作簡單裝飾項的類別。此範例裝飾項只用圓形來裝飾 UIElement 的角落。

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

// 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);
  }
}

下列影像顯示已套用至 TextBox 的 SimpleCircleAdorner。

裝飾項範例：已裝飾的文字方塊

裝飾項的呈現行為

請特別注意，裝飾項不包含任何繼承呈現行為，以確保裝飾項呈現是裝飾項實作器的職責。實作呈現行為的常見方式，就是覆寫 OnRender 方法並視需要使用一個或多個 DrawingContext 物件來呈現裝飾項的視覺化項目 (如上述範例所示)。

注意事項
任何放在裝飾項層中的項目，都會呈現在其餘您所設定之樣式的上面。換言之，裝飾項看起來永遠在最上面，而且無法使用疊置順序加以覆寫。

事件和點擊測試

就像其他 FrameworkElement 一樣，裝飾項會接收輸入事件。因為裝飾項的疊置順序永遠高於它所裝飾的項目，所以裝飾項會收到輸入事件 (例如 Drop 或 MouseMove)，這些事件可能主要用於基礎的裝飾項目。裝飾項可以接聽某些輸入事件，並藉由重新引發事件而將這些輸入事件傳遞到基礎裝飾項目。

若要啟用裝飾項之下項目的傳遞 (Pass-Through) 點擊測試，請將裝飾項的點擊測試 IsHitTestVisible 屬性設定為 false。如需點擊測試的詳細資訊，請參閱

視覺分層中的點擊測試

裝飾單一 UIElement

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

呼叫靜態方法 GetAdornerLayer 取得 AdornerLayer 物件，以便裝飾 UIElement。 GetAdornerLayer 會在視覺化樹狀結構中，從指定的 UIElement 向上查核，並傳回找到的第一個裝飾項層 (如果找不到裝飾項層，則方法會傳回 null)。
呼叫 Add 方法，將裝飾項繫結至目標 UIElement。

下列範例會將 SimpleCircleAdorner (如上所示) 繫結至名稱為 myTextBox 的 TextBox。

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

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

注意事項
目前不支援使用Extensible Application Markup Language (XAML) 將裝飾項繫結至另一個項目。

裝飾面板的子系

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

呼叫 static 方法 GetAdornerLayer，以尋找您要為其子系進行裝飾之項目的裝飾項層。
列舉父項目的所有子系並呼叫 Add 方法，將裝飾項繫結至每個子項目。

下列範例會將 SimpleCircleAdorner (如上所示) 繫結至名稱為 myStackPanel 之 StackPanel 的子系。

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

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

請參閱

共用方式為