ItemContainer 控制項模式

  • 發行項

描述實作 IItemContainerProvider的指導方針和慣例，包括方法的相關資訊。 ItemContainer控制項模式是用來支援專案虛擬化。

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

例如，下圖顯示包含數千個虛擬化專案的清單方塊。 由於控制項只會針對目前可見的子專案維護完整資訊，因此提供者只能針對專案 100- 127 公開 Microsoft 消費者介面自動化元素。

此圖顯示清單方塊中已虛擬化且未虛擬化的專案

使用虛擬化的控制項代表挑戰，因為只有已實現的 () 專案可完全當做消費者介面自動化樹狀結構中的消費者介面自動化元素使用。 虛擬化專案不存在於樹狀結構中，因此無法使用它們的相關資訊。

為了提供虛擬化專案的相關資訊，提供者會實作 ItemContainer 控制項模式，這會公開 IItemContainerProvider 介面。 FindItemByProperty方法會根據特定屬性的值來尋找子專案，例如Name、AutomationId或IsSelected。 如果專案虛擬化，FindItemByProperty會擷取專案的消費者介面自動化預留位置專案。 預留位置元素是僅支援VirtualizedItem控制項模式的IRawElementProviderSimple介面實作。

IVirtualizedItemProvider：：Realize方法可讓用戶端要求虛擬化專案實現，藉此公開專案的完整消費者介面自動化專案，讓所有必要屬性和模式都可供使用。

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

本主題包含下列各節。

實作方針和慣例

實作 ItemContainer 控制項模式時，請注意下列指導方針和慣例：

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

下列指導方針和需求適用于 IItemContainerProvider：：FindItemByProperty 方法。

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

下列指導方針和需求適用于消費者介面自動化樹狀結構中虛擬化專案的預留位置元素。

  • 雖然鼓勵提供者支援預留位置元素的更多屬性和控制項模式，但只需要 VirtualizedItem 控制項模式。
  • 當 再次呼叫 IItemContainerProvider：：FindItemByProperty 時，提供者可能會使先前的預留位置元素失效。 (如果用戶端需要實現預留位置元素，則應該立即執行此動作;否則，如果再次呼叫 FindItemByProperty ，或檢視區因任何原因而變更，則元素可能會失效。)
  • 捲動或調整大小的 UI 動作可能會導致容器的檢視區變更，並讓一組新的子專案變成可見。 在此情況下，先前擷取的預留位置專案可能無法在消費者介面自動化樹狀目錄中使用。
  • 提供者不應該虛擬化容器物件檢視區中可用的 UI 元素。

IItemContainerProvider 的必要成員

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

必要成員 成員類型 備註
FindItemByProperty 方法 無

 

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

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

UI 自動化控制項模式概觀

UI 自動化樹狀目錄概觀

VirtualizedItem 控制項模式