清單控制項類型

  • 發行項

本主題提供清單控制項類型的 Microsoft 消費者介面自動化支援相關資訊。

清單控制項類型提供一種方式來組織一般群組或專案群組，並允許使用者選取一或多個這些專案。 List控制項類型對於它可能包含的子項目類型有鬆散限制。 這可讓使用者介面自動化提供者支援選取範圍容器的已知項目。

下列各節會定義List控制項類型的必要消費者介面自動化樹狀結構、屬性、控制項模式和事件。 消費者介面自動化需求適用于 UI 架構/平臺整合消費者介面自動化控制項類型和控制項模式支援的所有清單控制項。

本主題包含下列各節。

一般樹狀結構

下表描述與清單控制項相關的消費者介面自動化樹狀結構的典型控制項和內容檢視，並描述每個檢視中可包含的內容。 如需 UI 自動化樹狀結構的詳細資訊，請參閱 UI 自動化樹狀結構概觀。

控制項檢視 內容檢視
包含對應控制項的項目。 從樹狀結構中移除備援資訊，讓輔助技術能與使用者有意義的最小資訊集搭配使用。
  • List
    • DataItem (0 個以上)
    • ListItem (0 個以上)
    • Group (0 個以上)
    • ScrollBar (0、1 或 2 個)
  • List
    • DataItem (0 個以上)
    • ListItem (0 個以上)
    • Group (0 個以上)

針對實作清單控制項類型的控制項 (例如清單控制項)，其控制項檢視包含：

  • 清單控制項內的零個或多個專案 (專案可以根據 ListItem 或 DataItem 控制項類型)
  • 清單控制項中零個以上的群組控制項
  • 0、1 或 2 個捲軸控制項

針對實作清單控制項類型的控制項 (例如清單控制項)，其內容檢視包含：

  • 清單控制項內的零個或多個專案 (專案可以根據 ListItem 或 DataItem 控制項類型)
  • 清單控制項中零個以上的群組

除了集中成群組的項目，清單控制項所包含的項目不能有階層式關聯性。 如果專案在消費者介面自動化樹狀結構中有子系，則清單容器應該以樹狀結構控制項類型為基礎。

清單控制項內可選取的項目，將從清單控制項的 UI 自動化樹狀結構中的子系取得。 清單控制項內的所有項目都必須屬於相同的選取群組。 清單中的可選取專案應該公開為 ListItem (，而不是 DataItem) 控制項類型。

相關屬性

下表列出值或定義與List控制項類型特別相關的消費者介面自動化屬性。 如需消費者介面自動化屬性的詳細資訊，請參閱從 消費者介面自動化 Elements 擷取屬性。

使用者介面自動化屬性 值 注意
UIA_AutomationIdPropertyId 請參閱備註。 此屬性的值在消費者介面自動化樹狀結構的原始檢視中的所有對等專案之間必須是唯一的。
UIA_BoundingRectanglePropertyId 請參閱備註。 包含整個控制項的最外層矩形。
UIA_ClickablePointPropertyId 請參閱備註。 如果清單控制項具有可點選的點 (可以按一下以讓清單取得焦點) 點，則必須透過此屬性公開該點。 如果 UIA_IsOffscreenPropertyId 屬性值為 TRUE，嘗試擷取此屬性會導致 UIA_E_NOCLICKABLEPOINT 錯誤。
UIA_ControlTypePropertyId 清單
UIA_HelpTextPropertyId 請參閱備註。 清單控制項的說明文字應解釋為什麼會要求使用者從清單選擇選項。 例如，「從此清單選取項目將會設定顯示器的解析度。」
UIA_IsContentElementPropertyId TRUE 此清單控制項一律包含在 UI 自動化樹狀結構的內容檢視中。
UIA_IsControlElementPropertyId TRUE 此清單控制項一律包含在 UI 自動化樹狀結構的控制項檢視中。
UIA_IsKeyboardFocusablePropertyId 請參閱備註。 如果控制項可接收鍵盤焦點，就必定支援此屬性。
UIA_LabeledByPropertyId 請參閱備註。 如果有靜態文字標籤，那麼這個屬性必須公開該控制項的參考。
UIA_LocalizedControlTypePropertyId 請參閱備註。 對應至 清單 控制項類型的當地語系化字串。 en-US 或英文 (美國) 的預設值為 「list」。
UIA_NamePropertyId 請參閱備註。 清單控制項的 Name 屬性的值應該會傳達要求使用者選取的選項類別。 此屬性通常會從靜態文字標籤取得其名稱。 如果沒有靜態文字標籤，應用程式開發人員必須公開 Name 屬性的值。
清單控制項唯一不需要此屬性的情況是，當控制項用於其他控制項的樹狀子目錄時。

必要的控制項模式和屬性

下表列出所有清單控制項必須支援的消費者介面自動化控制項模式。 如需控制項模式的詳細資訊，請參閱 UI Automation Control Patterns Overview。

控制項模式/模式屬性 支援/值 備註
IGridProvider 相依 當格線導覽需要依專案依專案提供時，實作 網格 線控制項模式。
IMultipleViewProvider 相依 如果控制項可以支援容器中專案的多個檢視，請實作 MultipleView 控制項模式。
IScrollProvider 相依 如果容器中的專案可捲動，請實作 卷 動控制項模式。
ISelectionProvider 相依 如果控制項支援支援選取範圍的清單控制項類型，當控制項包含的專案之間維護選取狀態時，控制項必須實作 Selection 控制項模式。 如果控制項內的專案無法選取，則可以使用 群組 控制項類型。
CanSelectMultiple 相依 清單控制項可以是單一或多重選擇容器。
IsSelectionRequired 相依 清單控制項不一定需要選取某個項目。
ITableProvider 永不 清單控制項類型永遠不會支援資料表控制項模式。 如果控制項需要支援此控制項模式，控制項應該以 DataGrid 控制項類型為基礎。

必要的事件

下表列出清單控制項所需的消費者介面自動化事件。 如需 UI Automation Events Overview事件的詳細資訊，請參閱

UI 自動化事件 備註
UIA_AutomationFocusChangedEventId
UIA_BoundingRectanglePropertyId 屬性變更事件。
UIA_IsEnabledPropertyId 屬性變更事件。 如果控制項支援 IsEnabled 屬性，它必須支援這個事件。
UIA_IsOffscreenPropertyId 屬性變更事件。 如果控制項支援 IsOffscreen 屬性，它必須支援這個事件。
UIA_LayoutInvalidatedEventId 如果子專案的版面配置可以變更，控制項必須支援此事件。
UIA_MultipleViewCurrentViewPropertyId 屬性變更事件。 如果控制項支援 MultipleView 控制項模式，則必須支援此事件。
UIA_ScrollHorizontallyScrollablePropertyId 屬性變更事件。 如果控制項支援 Scroll 控制項模式，它必須支援這個事件。
UIA_ScrollHorizontalScrollPercentPropertyId 屬性變更事件。 如果控制項支援 Scroll 控制項模式，它必須支援這個事件。
UIA_ScrollHorizontalViewSizePropertyId 屬性變更事件。 如果控制項支援 Scroll 控制項模式，它必須支援這個事件。
UIA_ScrollVerticalScrollPercentPropertyId 屬性變更事件。 如果控制項支援 Scroll 控制項模式，它必須支援這個事件。
UIA_ScrollVerticallyScrollablePropertyId 屬性變更事件。 如果控制項支援 Scroll 控制項模式，它必須支援這個事件。
UIA_ScrollVerticalViewSizePropertyId 屬性變更事件。 如果控制項支援 Scroll 控制項模式，它必須支援這個事件。
UIA_Selection_InvalidatedEventId 如果控制項支援 Selection 控制項模式，它必須支援這個事件。
UIA_StructureChangedEventId

概念

UI 自動化控制項類型概觀

UI 自動化概觀