共用方式為


VisualTreeHelper.FindElementsInHostCoordinates 方法

定義

多載

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 座標上,則傳回值會是空的。

傳回

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

屬性

範例

這是一個範例公用程式方法,可判斷指定 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 內的整體專案集中,則傳回值只會包含子 物件及其空間上繪製的專案。 如果 子樹 物件不存在於 交集框架 內,則傳回值會是空的。

傳回

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

屬性

範例

指定此 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 座標繪製的專案,以及可能完全或部分過度繪製的專案。 若要真正檢查過度繪製的情況,請使用使用 PointFindElementsInHostCoordinate 的多載,讓 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

傳回

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

屬性

範例

指定此 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 時,不會產生筆跡的元素會被視為點擊測試。 在此情況下,只要元素符合空間需求, (點與元素界限交集) ,它及其上階就會包含在結果中。

注意

某些特殊元素,例如 SwapChainPanelMediaPlayerElement,沒有筆刷,但仍會產生筆跡。

另請參閱

適用於

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

傳回

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

屬性

範例

指定此 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 與元素界限交集) ,它及其上階就會包含在結果中。

注意

某些特殊元素,例如 SwapChainPanelMediaPlayerElement,沒有筆刷,但仍會產生筆跡。

另請參閱

適用於