VisualTreeHelper.FindElementsInHostCoordinates 方法

參考

定義

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

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

多載

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 < UIElement> 。

另請參閱

適用於

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 的區域內。如果是的話，您可以指定與 intersectingRect 相交 的區域，並指定您要尋找的專案做為子樹參數。如果傳回值不是空的，這表示元素存在於該區域中的某處。當您點擊測試區域時，傳回集中的順序對於判斷迭置順序並不實用，因為集合包含一個以上的 x-y 座標的專案。集合會混合以各種 x-y 座標繪製的專案，以及可能完全或部分過度繪製的元素。若要真正檢查過度繪製的情況，請使用使用 Point 的 FindElementsInHostCoordinates多載，讓 x-y 座標和視覺化樹狀結構順序不再是因素。請參閱 FindElementsInHostCoordinates (Point，UIElement) 。

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

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

另請參閱

滑鼠互動

適用於

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 座標的整體元素集中，則傳回值只會包含子樹物件，以及任何具有高於子樹狀結構之子樹的物件，並以迭置順序的反轉列出。如果子樹物件不存在於 intersectingPoint 座標，則傳回值會是空的。

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 的色彩設定為 Transparent 仍會產生筆跡。只有 Null 筆刷不會產生筆跡。不考慮 Opacity 屬性。即使不透明度為 0，元素仍會產生筆跡。

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

注意

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

另請參閱

適用於

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內的整體專案集中，則傳回值只會包含在其空間上方繪製的子樹物件和專案。如果子樹物件不存在於 intersectingRect 框架內，則傳回值會是空的。

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
}

備註

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

注意

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

另請參閱

適用於

VisualTreeHelper.FindElementsInHostCoordinates 方法

定義

多載

FindElementsInHostCoordinates(Point, UIElement)

參數

傳回

範例

備註

基本點擊測試

元素篩選的點擊測試

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

另請參閱

適用於

FindElementsInHostCoordinates(Rect, UIElement)

參數

傳回

範例

備註

基本點擊測試

元素篩選的點擊測試

另請參閱

適用於

FindElementsInHostCoordinates(Point, UIElement, Boolean)

參數

傳回

範例

備註

另請參閱

適用於

FindElementsInHostCoordinates(Rect, UIElement, Boolean)

參數

傳回

範例

備註

另請參閱

適用於

意見反應

意見反應

其他資源