共用方式為


ItemContainer 控件模式

說明實作 IItemContainerProvider的指導方針和慣例,包括方法的相關信息。 ItemContainer 控件模式可用來支援專案虛擬化。

包含大量子專案的控件可以使用虛擬化來有效率地管理專案。 透過虛擬化,控件會在記憶體中維護所有指定時間只保留專案子集的完整資訊。 一般而言,子集只包含使用者目前可見的專案。 剩餘虛擬化專案的完整資訊會保留在記憶體中,並載入記憶體中,或當控件需要它時,例如,當使用者看到新專案時,就會實現它。

例如,下圖顯示包含數千個虛擬化項目的清單框。 因為控件只會針對目前可見的子項目維護完整資訊,因此提供者只能針對專案 100-127 公開Microsoft UI 自動化元素。

圖表,顯示已虛擬化且未虛擬化清單框中的專案

使用虛擬化的控件代表挑戰,因為只有實現的(已取消虛擬化)專案才能完全作為UI自動化樹狀目錄中的UI自動化元素使用。 虛擬化專案不存在於樹狀結構中,因此無法使用其相關信息。

為了提供虛擬化專案的相關信息,提供者會實作 ItemContainer 控件模式,這會公開 IItemContainerProvider 介面。 FindItemByProperty 方法會根據特定屬性的值來尋找子專案,例如 NameAutomationIdIsSelected。 如果項目虛擬化,FindItemByProperty 擷取專案的 UI 自動化佔位符元專案。 占位符元素是 IRawElementProviderSimple 介面的實作,僅支援 VirtualizedItem 控件模式。

IVirtualizedItemProvider::Realize 方法可讓用戶端要求實現虛擬化專案,從而公開專案的完整 UI 自動化專案,讓所有必要的屬性和模式可供使用。

雖然 ItemContainer 控件模式的主要用途是支持虛擬化容器案例,但不論容器是否使用虛擬化,都可以由任何依名稱擷取子專案的容器實作。

本主題包含下列各節。

實作指導方針和慣例

實作 ItemContainer 控件模式時,請注意下列指導方針和慣例:

  • 任何可包含虛擬化專案的控件都必須支援 ItemContainer 控件模式。 不論容器是否使用虛擬化,任何支援根據屬性值擷取專案的容器都可以支援此模式。
  • 當容器虛擬化時,其他控件模式,例如 SelectionTableGrid 都會受到影響。 例如,ISelectionProvider::GetSelection 方法可能只支援檢視區中的元素,或只支援目前未虛擬化的選取專案。
  • 卷動 控件模式應該不受虛擬化影響。
  • 虛擬化項目沒有可用的項目計數或索引資訊。 虛擬化控件可以使用 DescribedByItemStatus 屬性,視需要提供這項資訊。
  • 控件開發人員應該記錄併發佈受虛擬化使用影響之所有UI自動化屬性和控件模式的詳細數據。 雖然 ItemContainer 和 VirtualizedItem 控件模式提供基本支援,但它們可能不支援某些虛擬化行為。

下列指導方針和需求適用於 IItemContainerProvider::FindItemByProperty 方法。

  • 雖然不需要,Microsoft強烈建議 FindItemByProperty 支援 NameAutomationIdIsSelected 属性。
  • FindItemByProperty 需要周遊多個對象來尋找相符的物件,可能會變慢。
  • FindItemByProperty 可以重複呼叫,以依序尋找專案。 只要每個專案只傳回一次,專案就可以依任何順序排列。
  • FindItemByProperty 可以實作,只尋找出現在 UI 自動化樹狀結構控件或內容檢視中的元素。 只出現在原始檢視中的元素可以略過,以避免擷取只代表使用者「專案」部分的多個元素。
  • 當搜尋準則符合虛擬化專案時,提供者可以傳回支援 VirtualizedItem 控件模式的佔位符專案。 下列指導方針適用於佔位元元元素:
    • 擷取虛擬化專案的佔位元元專案不能造成UI變更。
    • 佔位元元項目必須是其他子元素的對等專案(需要結構變更的事件)。
    • 可能的話,提供者可以建立完整的自動化專案,而不是佔位元。
  • 當搜尋準則符合非虛擬化專案時,提供者必須傳回實際專案,而不是佔位符。
  • 找不到任何專案時,IItemContainerProvider::FindItemByProperty將 pFound 參數設定為 NULL,並傳回 S_OK
  • propertyId 參數為 0 時,提供者應該在 pStartAfter 之後傳回下一個專案。
  • 如果 pStartAfter 參數NULL,且 propertyId 為 0,提供者應該會傳回容器中的第一個專案。
  • propertyId 參數為0時,會忽略 value 參數。

下列指導方針和需求適用於UI自動化樹狀目錄中虛擬化專案的佔位元元素。

  • 雖然鼓勵提供者支援佔位符元素的更多屬性和控件模式,但只需要 VirtualizedItem 控件模式。
  • 再次呼叫 IItemContainerProvider::FindItemByProperty 時,提供者可能會使先前的佔位符元素失效。 (如果用戶端需要立即實現佔位符元素,則它應該立即執行;否則,如果再次呼叫 findItemByProperty ,或檢視區因任何原因而變更,則元素可能會失效。
  • 捲動或重設大小的UI動作可能會導致容器的檢視區變更,以及一組新的子專案變成可見。 在此情況下,使用者介面自動化樹狀目錄中可能無法使用先前擷取的佔位符元素。
  • 提供者不應該虛擬化容器物件檢視區中螢幕上可用的UI元素。

IItemContainerProvider 的必要成員

實作 IItemContainerProvider 介面需要下列方法。

必要成員 成員類型 筆記
FindItemByProperty 方法 沒有

 

ItemContainer 控件模式沒有相關聯的屬性或事件。

控件類型及其支援的控制模式

UI 自動化控制項模式概觀

UI 自動化樹狀結構概觀

VirtualizedItem 控件模式