共用方式為

VisualTreeHelper.FindElementsInHostCoordinates 方法

  • 參考

定義

命名空間:
Microsoft.UI.Xaml.Media

多載

FindElementsInHostCoordinates(Point, UIElement)

擷取一組對象，這些對象位於應用程式 UI 的指定 x-y 座標點內。 物件集代表共用該點之可視化樹狀結構的元件。
FindElementsInHostCoordinates(Rect, UIElement)

擷取位於應用程式UI指定 Rect 框架內的一組物件。 物件集代表共用矩形區域之可視化樹狀結構的元件，而且可能包含過度繪製的專案。
FindElementsInHostCoordinates(Point, UIElement, Boolean)

擷取一組對象，這些對象位於應用程式 UI 的指定 x-y 座標點內。 物件集代表共用該點之可視化樹狀結構的元件。
FindElementsInHostCoordinates(Rect, UIElement, Boolean)

擷取位於應用程式UI指定 Rect 框架內的一組物件。 物件集代表共用矩形區域之可視化樹狀結構的元件，而且可能包含過度繪製的專案。

FindElementsInHostCoordinates(Point, UIElement)

編輯

擷取一組對象，這些對象位於應用程式 UI 的指定 x-y 座標點內。 物件集代表共用該點之可視化樹狀結構的元件。

public:
 static IIterable<UIElement ^> ^ FindElementsInHostCoordinates(Point intersectingPoint, UIElement ^ subtree);
/// [Windows.Foundation.Metadata.DefaultOverload]
/// [Windows.Foundation.Metadata.Overload("FindElementsInHostCoordinatesPoint")]
 static IIterable<UIElement> FindElementsInHostCoordinates(Point const& intersectingPoint, UIElement const& subtree);
[Windows.Foundation.Metadata.DefaultOverload]
[Windows.Foundation.Metadata.Overload("FindElementsInHostCoordinatesPoint")]
public static IEnumerable<UIElement> FindElementsInHostCoordinates(Point intersectingPoint, UIElement subtree);
function findElementsInHostCoordinates(intersectingPoint, subtree)
Public Shared Function FindElementsInHostCoordinates (intersectingPoint As Point, subtree As UIElement) As IEnumerable(Of UIElement)

參數

intersectingPoint
Point

做為判斷點的點。 這個點使用應用程式視窗的座標空間，而不是任何特定元素 (，而且如果指定) 則不是 子樹 。

subtree
UIElement

要搜尋的物件。 如果 子樹 物件存在於存在於指定 交集Point 座標的整體元素集中，則傳回值只會包含 子樹 物件，以及任何具有高於 子樹狀結構之 z 順序的物件，由迭置順序的反轉列出。 如果 子樹 物件不存在於 交集Point 座標上，則傳回值會是空的。

傳回

IIterable<UIElement>

IEnumerable<UIElement>

可視化樹狀結構組合中一組可列舉的 UIElement 物件，該物件會以迭置順序的反轉列出。

屬性
DefaultOverloadAttribute OverloadAttribute

範例

這是一個範例公用程式方法，可判斷指定 Name 的元素是否存在於應用程式 UI 中 Point 的 Z 順序中。

private bool DoesPointContainElement(Point testPoint, string elementName, UIElement referenceFrame)
{
    IEnumerable<UIElement> elementStack = 
      VisualTreeHelper.FindElementsInHostCoordinates(testPoint, referenceFrame);
    foreach (UIElement item in elementStack)
    {
        FrameworkElement feItem = item as FrameworkElement; 
//cast to FrameworkElement, need the Name property
        if (feItem != null)
        {
            if (feItem.Name.Equals(elementName))
            {
                 return true;
            }
        }
     }
     // elementName was not in this stack 
     return false;
}

備註

傳回值不是單一元素，它是集合。 集合可以有多個元素，因為可能會以 Z 順序彼此堆疊多個 UI 元素。 輸入事件處理程式公開的傳統點擊測試技術，例如 PointerPressed 事件的傳送者值，只會考慮具有最高 Z 順序的最上層元素。 FindElementsInHostCoordinates 方法會傳回應用程式 UI 中共用該點或區域的整個元素堆棧，並依迭置順序的反轉列出。 因此，使用 FindElementsInHostCoordinates 有助於檢查您刻意或不小心堆疊元素的情況。 您可能想要更正轉譯和點擊測試的順序，或基於其他原因檢查該順序。

FindElementsInHostCoordinates 適用於三種案例：基本點擊測試、篩選特定元素的點擊測試，以及判斷可視化樹狀結構中是否有元素在相同點過度繪製。

基本點擊測試

針對基本點擊測試，目標是在 x-y 座標中，探索應用程式 UI 的 Z 順序最高元素。 除了在轉譯 UI 中繪製最上層的專案之外，此元素也很重要，因為如果有用戶互動，例如指標事件，則此元素也是報告的事件來源。 您可能遇到點擊測試案例，其中您想要知道在發生任何輸入事件之前，哪些元素存在於最上層的迭置順序，以便您可以預測它，並可能更正圖層順序放置中的任何錯誤。

在此案例中，您應該傳遞您有興趣點擊測試的點作為 交集Point 參數的值。 針對 子樹 參數，您可以將它傳遞為 Null。 或者，您可以將 子樹 指定為您知道的某個元素是頁面的根視覺效果，或是您想要成為點擊測試最後一個停止點的專案。

圖層順序最上層的專案一律是傳回之 UIElement 專案之 IEnumerable 中的第一個專案。 因此，對於基本點擊測試，您通常只對第一個項目感興趣。 IEnumerable 中的任何其他專案都是其他元素，這些元素也位於該時間點，但會進一步回到 Z 順序，並繪製在該第一個專案底下。 進一步傳回的專案不會自行回報為該時間點的輸入事件來源，只有最上層的專案才會回報。

元素篩選的點擊測試

有時候您想要知道特定元素是否存在於UI中的特定點。 若是如此，您可以指定與 Point 交集 的點，並指定您要尋找的專案做為 子樹 參數。 如果傳回值不是空的，這表示元素存在於UI中的該點。 如果元素是傳回值中的第一個專案，這表示元素在 交集Point 的迭置順序中最上層。 如果傳回值中有其他專案，而且 子樹 狀結構不是第一個專案，其他專案則代表以 z 順序 (較高之 交集Point 呈現的專案，這些專案會在 子樹 元素頂端呈現) 。 在此情況下， 子樹 是傳回 的 IEnumerable 中的最後一個專案，而不是第一個專案。

如果傳回值是空的，表示 子樹 元素不存在於任何迭置順序值。

尋找過度繪製或查看完整的可視化樹狀結構

UI 可以是動態的，特別是如果您使用來自UI母體擴展之數據系結的集合。 因此，有時候需要知道目前位於哪個元素之上。 您可能預期使用者在應用程式中可能會互動，並確認您目前想要的互動是否可行。 在此案例中，您通常會指定代表一些已知點的 Point 值，例如目前應用程式視窗中的有效座標 (0,0) 。 針對 子樹 參數，您可以將它傳遞為 Null。 或者，您可以將 子樹 指定為您知道的某個元素是頁面的根視覺效果，或是您想要成為點擊測試最後一個停止點的專案。

注意

如果您為子樹傳遞 null，您可能會看到可視化樹狀結構包含頁面層級 XAML 未定義的元素，例如 Frame 元素和 ContentPresenter。 這些來自UWP app的大部分 Microsoft Visual Studio 專案範本中存在的一般應用程式初始化程式代碼，其會先建立 Frame 成為 Window.Content 值。 如 FindElementsInHostCoordinates 方法所示的可視化樹狀結構會延伸至 Window.Content，除非您以 Page 根目錄之類的子樹元素進行篩選。

在傳回值中，您可能會對內的每個項目感興趣。 因此，您可以使用 foreach 或類似的語言特定技術來逐一查看集合，並在每個元素上執行您自己的邏輯。 請記住，該集合中的第一個專案是以 z 順序排列的最上層元素。

如果您是使用 C# 或 Microsoft Visual Basic 進行程式設計，這個方法的傳回值類型會投影為包含 UIElement 專案的 IEnumerable 泛型集合。 如果您是使用 Visual C++ 元件延伸模組進行程式設計， (C++/CX) ，則此方法的傳回類型為 IIterable。

另請參閱

適用於

FindElementsInHostCoordinates(Rect, UIElement)

編輯

擷取位於應用程式UI指定 Rect 框架內的一組物件。 物件集代表共用矩形區域之可視化樹狀結構的元件，而且可能包含過度繪製的專案。

public:
 static IIterable<UIElement ^> ^ FindElementsInHostCoordinates(Rect intersectingRect, UIElement ^ subtree);
/// [Windows.Foundation.Metadata.Overload("FindElementsInHostCoordinatesRect")]
 static IIterable<UIElement> FindElementsInHostCoordinates(Rect const& intersectingRect, UIElement const& subtree);
[Windows.Foundation.Metadata.Overload("FindElementsInHostCoordinatesRect")]
public static IEnumerable<UIElement> FindElementsInHostCoordinates(Rect intersectingRect, UIElement subtree);
function findElementsInHostCoordinates(intersectingRect, subtree)
Public Shared Function FindElementsInHostCoordinates (intersectingRect As Rect, subtree As UIElement) As IEnumerable(Of UIElement)

參數

intersectingRect
Rect

要作為判斷區域的 Rect 。 此框架使用應用程式視窗的座標空間，而不是任何特定元素 (，而且如果指定) ，則不會使用 子樹 。

subtree
UIElement

要搜尋的物件。 如果 子樹 物件存在於存在於指定 交集Rect 內的整體專案集中，則傳回值只會包含子 樹 物件及其空間上繪製的專案。 如果 子樹 物件不存在於 交集框架 內，則傳回值會是空的。

傳回

IIterable<UIElement>

IEnumerable<UIElement>

一組可列舉的 UIElement 對象，這些對象位於指定 之 Rect 框架中的可視化樹狀結構組合中。

屬性
OverloadAttribute

範例

指定此 XAML UI：

<Canvas Name="canvas">
  <Rectangle Name="outermost" Fill="Red" Width="200" Height="200"/>
  <Rectangle Canvas.Left="40" Canvas.Top="40" Name="hidden" Fill="Green" Width="120" Height="120"/>
  <Rectangle Canvas.Left="40" Canvas.Top="40" Name="shown" Fill="Orange" Width="120" Height="120"/>
  <Rectangle Canvas.Left="80" Canvas.Top="80" Name="center" Fill="Yellow" Width="40" Height="40"/>
  <Rectangle Canvas.Left="190" Canvas.Top="190" Name="bottomright" Fill="Pink" Width="10" Height="10"/>
</Canvas>

以下是使用不同 子樹 值之 FindElementsInHostCoordinates 的一些範例使用方式和結果：

private void Test(object sender, RoutedEventArgs e)
{
    IEnumerable<UIElement> hits;
    hits =  VisualTreeHelper.FindElementsInHostCoordinates(
      new Rect(75,75,50,50), canvas);
    foreach (UIElement element in hits)
    {
        //run logic here, such as log the results 
    }
// results in the following set of elements, listed by Name:
// center - the last declared XAML element is first returned, if within the area
// shown - renders, underneath 'center' in part of the area but visible on the edges
// hidden - entirely under 'shown', not visible but part of the area, an overdraw
// outermost - draws under all the above
// canvas - the 'subtree' value, and the last element reported

    hits = VisualTreeHelper.FindElementsInHostCoordinates(
      new Rect(75,75,50,50), center);
    foreach (UIElement element in hits) {
        //run logic here, such as log the results
    }
// results in only 'center', because it was 'subtree' and it's also topmost

    hits = VisualTreeHelper.FindElementsInHostCoordinates(
      new Rect(75,75,50,50), bottomright);
// results in an empty set, 'bottomright' isn't in the specified rect
}

備註

傳回值不是單一元素，它是集合。 集合可以有多個元素，因為可能會以 Z 順序彼此堆疊多個 UI 元素，而且在 交集Rect 框架中完全或部分地有多個元素。 輸入事件處理程式公開的傳統點擊測試技術，例如 PointerPressed 事件的傳送者值，只會考慮具有最高 Z 順序的最上層元素。 FindElementsInHostCoordinates 方法會傳回共用應用程式 UI 中該點或區域的整個元素堆棧，這些元素是由可視化樹狀結構順序所列出的 (，這通常與 XAML 宣告順序的反向) 相同。 因此，使用 FindElementsInHostCoordinates 有助於檢查您刻意或不小心堆疊元素的情況。 您可能想要更正轉譯和點擊測試的順序，或基於其他原因檢查該順序。

在區域上 FindElementsInHostCoordinates 適用於兩個案例：基本點擊測試和點擊測試，其會篩選特定元素。

基本點擊測試

針對基本點擊測試，目標是探索應用程式UI的 Z 順序最高的元素。 如果您要對滑鼠互動進行點擊測試，可能會使用點，但針對觸控導向點擊測試，通常適合使用矩形區域。 您可能遇到點擊測試案例，其中您想要知道在發生任何觸控事件之前，位於頂端 z 順序的專案。 或者，您可能有一個想要展開為矩形的點，以查看靠近中心點的專案，以及哪些元素可能是預期的目標。

在此案例中，您應該傳遞您有興趣點擊測試的矩形作為 交集Rect 參數的值。 針對 子樹 參數，您可以將它傳遞為 Null。 或者，您可以將 子樹 指定為您知道的某個元素是頁面的根視覺效果，或是您想要成為點擊測試最後一個停止點的專案。

傳回之 UIElement 專案的 IEnumerable 元素順序會同時考慮區域中的座標空間和 z 順序。 因此，可以取得不是最高 Z 順序的項目點擊次數，因此無法成為輸入事件的來源。 若要確定，您可以使用與同一 個交集Rect ，但將感興趣的專案傳遞為 子樹，針對所傳回清單中的任何專案執行元素篩選的點擊測試。

元素篩選的點擊測試

有時候您想要知道特定元素是否存在於UI的區域內。 如果是，您可以指定該區域進行 交集Rect ，並指定您要尋找的專案做為 子樹 參數。 如果傳回值不是空的，這表示專案存在於該區域中的某處。 當您點擊測試區域時，傳回集中的順序對於判斷 z 順序並不實用，因為集合包含一個以上的 x-y 座標的專案。 集合混合了以各種 x-y 座標繪製的專案，以及可能完全或部分過度繪製的專案。 若要真正檢查過度繪製的情況，請使用使用 Point 的 FindElementsInHostCoordinate 的多載，讓 x-y 座標和可視化樹狀結構順序不再是因素。 請參閱 FindElementsInHostCoordinates (Point，UIElement) 。

如果傳回值是空的，表示 子樹 元素不存在於區域中。

如果您是使用 C# 或 Microsoft Visual Basic 進行程式設計，這個方法的傳回值類型會投影為包含 UIElement 專案的 IEnumerable 泛型集合。 如果您是使用 Visual C++ 元件延伸模組進行程式設計， (C++/CX) ，則此方法的傳回類型為 IIterable。

另請參閱

適用於

FindElementsInHostCoordinates(Point, UIElement, Boolean)

編輯

擷取一組對象，這些對象位於應用程式 UI 的指定 x-y 座標點內。 物件集代表共用該點之可視化樹狀結構的元件。

public:
 static IIterable<UIElement ^> ^ FindElementsInHostCoordinates(Point intersectingPoint, UIElement ^ subtree, bool includeAllElements);
/// [Windows.Foundation.Metadata.DefaultOverload]
/// [Windows.Foundation.Metadata.Overload("FindAllElementsInHostCoordinatesPoint")]
 static IIterable<UIElement> FindElementsInHostCoordinates(Point const& intersectingPoint, UIElement const& subtree, bool const& includeAllElements);
[Windows.Foundation.Metadata.DefaultOverload]
[Windows.Foundation.Metadata.Overload("FindAllElementsInHostCoordinatesPoint")]
public static IEnumerable<UIElement> FindElementsInHostCoordinates(Point intersectingPoint, UIElement subtree, bool includeAllElements);
function findElementsInHostCoordinates(intersectingPoint, subtree, includeAllElements)
Public Shared Function FindElementsInHostCoordinates (intersectingPoint As Point, subtree As UIElement, includeAllElements As Boolean) As IEnumerable(Of UIElement)

參數

intersectingPoint
Point

做為判斷點的點。 這個點使用應用程式視窗的座標空間，而不是任何特定元素 (，而且如果指定) 則不是 子樹 。

subtree
UIElement

要搜尋的物件。 如果 子樹 物件存在於存在於指定 交集Point 座標的整體元素集中，則傳回值只會包含 子樹 物件，以及任何具有高於 子樹狀結構之 z 順序的物件，由迭置順序的反轉列出。 如果 子樹 物件不存在於 交集Point 座標上，則傳回值會是空的。

includeAllElements
Boolean

bool

true 表示包含所有相交的專案，包括視為點擊測試看不到的元素。 false 表示只尋找可見且可點擊測試的專案。 預設值為 false。

傳回

IIterable<UIElement>

IEnumerable<UIElement>

一組可列舉的 UIElement 對象，決定位於指定點的可視化樹狀結構組合中，以迭置順序反轉列出。

屬性
DefaultOverloadAttribute OverloadAttribute

範例

指定此 XAML UI：

<Canvas Name="canvas">
  <Rectangle Name="outermost" Fill="Red" Width="200" Height="200"/>
  <Rectangle Canvas.Left="40" Canvas.Top="40" Name="hidden" Fill="Green" Width="120" Height="120"/>
  <Rectangle Canvas.Left="40" Canvas.Top="40" Name="shown" Fill="Orange" Width="120" Height="120"/>
  <Rectangle Canvas.Left="80" Canvas.Top="80" Name="center" Fill="Yellow" Width="40" Height="40"/>
  <Rectangle Canvas.Left="190" Canvas.Top="190" Name="bottomright" Fill="Pink" Width="10" Height="10"/>
</Canvas>

以下是使用不同 子樹 值之 FindElementsInHostCoordinates 的一些範例使用方式和結果：

private void Test(object sender, RoutedEventArgs e)
{
    IEnumerable<UIElement> hits;
    hits =  VisualTreeHelper.FindElementsInHostCoordinates(
      new Point(100,100), canvas, true);
    foreach (UIElement element in hits)
    {
        //run logic here, such as log the results 
    }
// results in the following set of elements, listed by Name:
// center - the element that is topmost in z-order at 100,100
// shown - also renders at 100,100 but is underneath 'center'
// hidden - is entirely underneath 'shown', 
//   and lower in z-order because 'hidden' declared before 'shown' in XAML
// outermost - draws under all the above at 100,100
// canvas - the 'subtree' value, so that's the last element reported

    hits = VisualTreeHelper.FindElementsInHostCoordinates(
      new Point(100, 100), center, true);
    foreach (UIElement element in hits) {
        //run logic here, such as log the results
    }
// results in 'center', because it is 'subtree' and also topmost

    hits = VisualTreeHelper.FindElementsInHostCoordinates(
      new Point(100, 100), bottomright, true);
// results in an empty set, 'bottomright' doesn't render at 100,100
}

備註

如果元素同時佔用版面配置中的空間並「產生筆跡」，就會被視為可點擊測試。 對於具有 Brush 的專案，即使 Brush 不會產生可見圖元，任何非 Null Brush 都會被視為會產生筆跡的專案。 例如， SolidColorBrush 的色彩設定為 透明 仍會產生筆跡。 只有 Null 筆刷不會產生筆跡。 不考慮 Opacity 屬性。 即使不透明度為 0，元素仍會產生筆跡。

當 includeAllElements 參數設定為 true 時，不會產生筆跡的元素會被視為點擊測試。 在此情況下，只要元素符合空間需求， (點與元素界限交集) ，它及其上階就會包含在結果中。

注意

某些特殊元素，例如 SwapChainPanel 和 MediaPlayerElement，沒有筆刷，但仍會產生筆跡。

另請參閱

適用於

FindElementsInHostCoordinates(Rect, UIElement, Boolean)

編輯

擷取位於應用程式UI指定 Rect 框架內的一組物件。 物件集代表共用矩形區域之可視化樹狀結構的元件，而且可能包含過度繪製的專案。

public:
 static IIterable<UIElement ^> ^ FindElementsInHostCoordinates(Rect intersectingRect, UIElement ^ subtree, bool includeAllElements);
/// [Windows.Foundation.Metadata.Overload("FindAllElementsInHostCoordinatesRect")]
 static IIterable<UIElement> FindElementsInHostCoordinates(Rect const& intersectingRect, UIElement const& subtree, bool const& includeAllElements);
[Windows.Foundation.Metadata.Overload("FindAllElementsInHostCoordinatesRect")]
public static IEnumerable<UIElement> FindElementsInHostCoordinates(Rect intersectingRect, UIElement subtree, bool includeAllElements);
function findElementsInHostCoordinates(intersectingRect, subtree, includeAllElements)
Public Shared Function FindElementsInHostCoordinates (intersectingRect As Rect, subtree As UIElement, includeAllElements As Boolean) As IEnumerable(Of UIElement)

參數

intersectingRect
Rect

要作為判斷區域的 Rect 。 此框架使用應用程式視窗的座標空間，而不是任何特定元素 (，而且如果指定) ，則不會使用 子樹 。

subtree
UIElement

要搜尋的物件。 如果 子樹 物件存在於存在於指定 交集Rect 內的整體專案集中，則傳回值只會包含子 樹 物件及其空間上繪製的專案。 如果 子樹 物件不存在於 交集框架 內，則傳回值會是空的。

includeAllElements
Boolean

bool

true 表示包含所有相交的專案，包括視為點擊測試看不到的元素。 false 表示只尋找可見且可點擊測試的專案。 預設值為 false。

傳回

IIterable<UIElement>

IEnumerable<UIElement>

一組可列舉的 UIElement 對象，決定位於指定 Rect 框架中的可視化樹狀結構組合中。

屬性
OverloadAttribute

範例

指定此 XAML UI：

<Canvas Name="canvas">
  <Rectangle Name="outermost" Fill="Red" Width="200" Height="200"/>
  <Rectangle Canvas.Left="40" Canvas.Top="40" Name="hidden" Fill="Green" Width="120" Height="120"/>
  <Rectangle Canvas.Left="40" Canvas.Top="40" Name="shown" Fill="Orange" Width="120" Height="120"/>
  <Rectangle Canvas.Left="80" Canvas.Top="80" Name="center" Fill="Yellow" Width="40" Height="40"/>
  <Rectangle Canvas.Left="190" Canvas.Top="190" Name="bottomright" Fill="Pink" Width="10" Height="10"/>
</Canvas>

以下是使用不同子樹值之 FindElementsInHostCoordinates 的一些範例使用方式和結果：

private void Test(object sender, RoutedEventArgs e)
{
    IEnumerable<UIElement> hits;
    hits =  VisualTreeHelper.FindElementsInHostCoordinates(
      new Rect(75,75,50,50), canvas, true);
    foreach (UIElement element in hits)
    {
        //run logic here, such as log the results 
    }
// results in the following set of elements, listed by Name:
// center - the last declared XAML element is first returned, if within the area
// shown - renders, underneath 'center' in part of the area but visible on the edges
// hidden - entirely under 'shown', not visible but part of the area, an overdraw
// outermost - draws under all the above
// canvas - the 'subtree' value, and the last element reported

    hits = VisualTreeHelper.FindElementsInHostCoordinates(
      new Rect(75,75,50,50), center, true);
    foreach (UIElement element in hits) {
        //run logic here, such as log the results
    }
// results in only 'center', because it was 'subtree' and it's also topmost

    hits = VisualTreeHelper.FindElementsInHostCoordinates(
      new Rect(75,75,50,50), bottomright, true);
// results in an empty set, 'bottomright' isn't in the specified rect
}

備註

如果元素同時佔用版面配置中的空間並「產生筆跡」，就會被視為可點擊測試。 對於具有 Brush 的專案，即使 Brush 不會產生可見圖元，任何非 Null Brush 都會被視為會產生筆跡的專案。 例如， SolidColorBrush 的色彩設定為 透明 仍會產生筆跡。 只有 Null 筆刷不會產生筆跡。 不考慮 Opacity 屬性。 即使不透明度為 0，元素仍會產生筆跡。

當 includeAllElements 參數設定為 true 時，不會產生筆跡的元素會被視為點擊測試。 在此情況下，只要元素符合空間需求， (rect 與元素界限交集) ，它及其上階就會包含在結果中。

注意

某些特殊元素，例如 SwapChainPanel 和 MediaPlayerElement，沒有筆刷，但仍會產生筆跡。

另請參閱

適用於