ListItem 控制項類型
本主題提供ListItem控制項類型的 Microsoft 消費者介面自動化支援相關資訊。
清單專案控制項是實作 ListItem 控制項類型的控制項範例。
下列各節會定義ListItem控制項類型所需的 消費者介面自動化樹狀結構、屬性、控制項模式和事件。 消費者介面自動化需求適用于 UI 架構/平臺整合消費者介面自動化控制項類型和控制項模式支援的所有清單專案控制項。
本主題包含下列各節。
一般樹狀結構
下表描述與清單專案控制項相關的消費者介面自動化樹狀結構的一般控制項和內容檢視，並描述每個檢視中可包含的內容。 如需 UI 自動化樹狀結構的詳細資訊，請參閱 UI 自動化樹狀結構概觀。
| 控制項檢視 | 內容檢視 |
|---|---|
|
|
在消費者介面自動化樹狀結構的內容檢視中，清單專案控制項的子系必須一律顯示零個子系。 如果控制項的結構讓清單專案底下包含其他專案，則應該遵循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 子項目。
相關主題