ListItem 控制項類型

  • 發行項

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

清單專案控制項是實作 ListItem 控制項類型的控制項範例。

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

本主題包含下列各節。

一般樹狀結構

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

控制項檢視 內容檢視
  • ListItem
    • 影像 (0 個以上)
    • 文字 (0 個以上)
    • 編輯 (0 個以上)
  • ListItem

 

在消費者介面自動化樹狀結構的內容檢視中，清單專案控制項的子系必須一律顯示零個子系。 如果控制項的結構讓清單專案底下包含其他專案，則應該遵循TreeItem控制項類型的消費者介面自動化支援需求。

相關屬性

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

使用者介面自動化屬性 值 注意
UIA_AutomationIdPropertyId 請參閱備註。 此屬性的值在消費者介面自動化樹狀結構的原始檢視中的所有對等專案之間必須是唯一的。 如果已知元素在使用者介面的不同實例之間保持一致，請為清單專案配置 AutomationId 屬性。 如果清單專案已動態填入且無法預測，請將 AutomationId 屬性保留空白。
UIA_BoundingRectanglePropertyId 請參閱備註。 這個屬性的值應包含清單項目的影像區域和文字內容。
UIA_ClickablePointPropertyId 相依 如果清單控制項具有可點選的點 (可以按一下以讓清單取得焦點) 點，則必須透過此屬性公開該點。 如果清單控制項完全由子代清單專案所涵蓋，則會傳回 UIA_E_NOCLICKABLEPOINT 錯誤，指出用戶端必須要求清單控制項內的專案以取得可點選點。
UIA_ControlTypePropertyId ListItem 此值與所有使用者介面架構的值相同。
UIA_HelpTextPropertyId 請參閱備註。 清單控制項的說明文字應解釋，為什麼會要求使用者從選項清單中選擇選項，而這通常也是透過工具提示顯示的資訊類型。 例如，「選取專案以設定監視器的顯示解析度」。
UIA_IsContentElementPropertyId TRUE 此清單控制項一律包含在 UI 自動化樹狀結構的內容檢視中。
UIA_IsControlElementPropertyId TRUE 此清單控制項一律包含在 UI 自動化樹狀結構的控制項檢視中。
UIA_IsKeyboardFocusablePropertyId 請參閱備註。 如果容器可以接受鍵盤輸入，則這個屬性值應該是 TRUE。
UIA_IsOffscreenPropertyId 相依 這個屬性必須傳回值，指出清單專案目前是否捲動到實作 Scroll 控制項模式的父容器內檢視。
UIA_ItemStatusPropertyId 相依 如果控制項包含動態更新的狀態，則必須支援這個屬性，讓輔助技術可以在元素的狀態變更時收到更新。
UIA_ItemTypePropertyId 相依 表示基礎物件的清單項目控制項應公開此屬性。 這些清單項目控制項通常會有相關聯的圖示，可讓使用者將控制項與基礎物件建立關聯。
UIA_LabeledByPropertyId 請參閱備註。 如果有靜態文字標籤，那麼這個屬性必須公開該控制項的參考。
UIA_LocalizedControlTypePropertyId 請參閱備註。 對應至 ListItem 控制項類型的當地語系化字串。 en-US 或英文 (美國) 的預設值為 「list item」。
UIA_NamePropertyId 請參閱備註。 清單專案控制項的名稱屬性值來自專案的文字標籤。

 

必要的控制項模式

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

控制項模式 支援 備註
IExpandCollapseProvider 相依 如果專案可以操作以顯示或隱藏資訊，則必須實作 ExpandCollapse 控制項模式。
IGridItemProvider 相依 如果清單容器內支援專案對專案空間導覽，而且容器會以資料列和資料行排列，則必須實作 GridItem 控制項模式。
IInvokeProvider 相依 如果專案具有可對它執行的命令，與選取範圍分開，則必須實作 Invoke 控制項模式。 這通常是與按兩下清單項目控制項相關聯的動作。 範例會從 Windows 檔案總管開機檔案，或在 Microsoft Windows 媒體播放機中播放音樂檔案。
IScrollItemProvider 相依 如果清單專案包含在可捲動的容器內，則必須實作 ScrollItem 控制項模式。
ISelectionItemProvider 相依 支援選取的清單專案控制項必須實作 SelectionItem 控制項模式。 這可讓清單項目控制項傳遞已選取的訊息。
IToggleProvider 相依 如果清單專案是可檢查的，而且動作不會執行選取狀態變更，則必須實作 切換 控制項模式。
IValueProvider 相依 如果可以編輯專案，則必須實作 Value 控制項模式。 清單專案控制項的變更會導致 變更UIA_NamePropertyId 和 UIA_ValueValuePropertyId 屬性的值。

 

必要的事件

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

UI 自動化事件 備註
UIA_AutomationFocusChangedEventId
UIA_BoundingRectanglePropertyId 屬性變更事件。
UIA_ExpandCollapseExpandCollapseStatePropertyId 屬性變更事件。 如果控制項支援 ExpandCollapse 控制項模式，它必須支援此事件。
UIA_Invoke_InvokedEventId 如果控制項支援 Invoke 控制項模式，它必須支援這個事件。
UIA_IsEnabledPropertyId 屬性變更事件。 如果控制項支援 IsEnabled 屬性，它必須支援這個事件。
UIA_IsOffscreenPropertyId 屬性變更事件。 如果控制項支援 IsOffscreen 屬性，它必須支援此事件。
UIA_ItemStatusPropertyId 屬性變更的事件。 如果控制項支援 ItemStatus 屬性，就必須支援這個事件。
UIA_NamePropertyId 屬性變更事件。
UIA_SelectionItem_ElementAddedToSelectionEventId 如果控制項支援 SelectionItem 控制項模式，它必須支援這個事件。
UIA_SelectionItem_ElementRemovedFromSelectionEventId 如果控制項支援 SelectionItem 控制項模式，它必須支援這個事件。
UIA_SelectionItem_ElementSelectedEventId 如果控制項支援 SelectionItem 控制項模式，它必須支援這個事件。
UIA_StructureChangedEventId
UIA_ToggleToggleStatePropertyId 屬性變更事件。 如果控制項支援 切換 控制項模式，它必須支援這個事件。
UIA_ValueValuePropertyId 屬性變更事件。 如果控制項支援 Value 控制項模式，它必須支援這個事件。

 

備註

如果容器裝載清單專案，則流覽的主要方法應該移至清單專案。 透過清單導覽將焦點放在子項目上可能會對使用者和協助工具工具造成混淆。 如果容器裝載垂直專案清單，按向上鍵和向下鍵應該流覽專案，但按下向右鍵和向左鍵可能會巡覽至焦點專案的子項目，例如清單欄或 UI 子項目。

概念

UI 自動化控制項類型概觀

UI 自動化概觀