ListItem 控制件類型
本主題提供 ListItem 控件類型的Microsoft UI 自動化支援相關信息。
清單專案控件是實作 ListItem 控件類型的控件範例。
下列各節會定義 ListItem 控件類型的必要 UI 自動化樹狀結構、屬性、控制項模式和事件。 使用者介面自動化需求適用於所有清單專案控制項，其中 UI 架構/平臺會整合控制項類型和控制項模式的 UI 自動化支援。
本主題包含下列各節。
一般樹狀結構
下表描述與清單專案控件相關的UI自動化樹狀結構一般控件和內容檢視，並描述每個檢視中可包含的內容。 如需 UI 自動化樹狀結構的詳細資訊，請參閱 UI 自動化樹狀結構概觀。
| 控件檢視 | 內容檢視 |
|---|---|
|
|
UI 自動化樹狀結構內容檢視內清單專案控件的子系必須一律顯示零個子系。 如果控件的結構讓列表專案底下包含其他專案，則應該遵循 TreeItem 控件類型的 UI 自動化支援需求。
相關屬性
下表列出UI自動化屬性，其值或定義與listItem 控件類型 特別相關。 如需 UI 自動化屬性的詳細資訊，請參閱 從 UI 自動化元素擷取屬性。
| UI 自動化屬性 | 價值 | 筆記 |
|---|---|---|
| UIA_AutomationIdPropertyId | 請參閱附注。 | 在UI自動化樹狀結構的原始檢視中，此屬性的值在所有對等專案之間必須是唯一的。 如果已知元素在使用者介面的不同實例之間保持一致，請配置清單專案的 AutomationId 屬性。 如果清單專案是動態填入且無法預測的，請將 AutomationId 保留空白 屬性。 |
| UIA_BoundingRectanglePropertyId | 請參閱附注。 | 此屬性的這個值應該包含清單專案的影像和文字內容區域。 |
| UIA_ClickablePointPropertyId | 取決於 | 如果清單控制項具有可點選的點（可以按兩下以讓清單取得焦點的點），則必須透過這個屬性公開該點。 如果清單控制項完全由子系列表專案所涵蓋，則會傳回 UIA_E_NOCLICKABLEPOINT 錯誤，指出客戶端必須向清單控制件內的專案詢問可點選點。 |
| UIA_ControlTypePropertyId | ListItem | 所有UI架構的這個值都相同。 |
| UIA_HelpTextPropertyId | 請參閱附注。 | 清單控件的說明文字應該說明為何要求使用者從選項清單中做出選擇，這通常是透過工具提示呈現的相同類型資訊。 例如，「選取專案以設定監視器的顯示解析度」。 |
| UIA_IsContentElementPropertyId | TRUE | 清單控制件一律包含在使用者介面自動化樹狀結構的內容檢視中。 |
| UIA_IsControlElementPropertyId | TRUE | 清單控制件一律包含在UI自動化樹狀結構的控件檢視中。 |
| UIA_IsKeyboardFocusablePropertyId | 請參閱附注。 | 如果容器可以接受鍵盤輸入，則這個屬性值應該 TRUE。 |
| UIA_IsOffscreenPropertyId | 取決於 | 此屬性必須傳回值，指出清單專案目前是否捲動至實作 Scroll 控件模式之父容器內的檢視。 |
| UIA_ItemStatusPropertyId | 取決於 | 如果控件包含動態更新的狀態，則必須支援這個屬性，以便輔助技術可以在元素的狀態變更時接收更新。 |
| UIA_ItemTypePropertyId | 取決於 | 對於代表基礎對象的清單專案控件，應該公開這個屬性。 這些清單專案控制項通常會有與用戶與基礎對象相關聯之控件相關聯的圖示。 |
| UIA_LabeledByPropertyId | 請參閱附注。 | 如果有靜態文字標籤，則此屬性必須公開該控件的參考。 |
| UIA_LocalizedControlTypePropertyId | 請參閱附注。 | 對應至 ListItem 控件類型的當地語系化字串。 預設值為 en-US 或英文（美國）的「清單專案」。 |
| UIA_NamePropertyId | 請參閱附注。 | 清單專案控制件的 name 屬性值來自專案的文字標籤。 |
必要的控制件模式
下表列出所有清單專案控制項都必須支援的UI自動化控制件模式。 如需控制樣式的詳細資訊，請參閱 UI 自動化控制樣式概觀。
| 控制件模式 | 支援 | 筆記 |
|---|---|---|
| IExpandCollapseProvider | 取決於 | 如果專案可以作以顯示或隱藏資訊，則必須實作 ExpandCollapse 控件模式。 |
| IGridItemProvider | 取決於 | 如果清單容器內支援專案對專案空間導覽，且容器會以數據列和數據行排列，則必須實作 GridItem 控件模式。 |
| IInvokeProvider | 取決於 | 如果專案具有可對它執行的命令，請與選取專案分開，則必須實作 Invoke 控件模式。 這通常是與按兩下清單專案控件相關聯的動作。 範例會從 Windows 檔案總管啟動檔，或在 windows Media Player Microsoft播放音樂檔案。 |
| IScrollItemProvider | 取決於 | 如果清單專案包含在可捲動的容器內，則必須實作 ScrollItem 控件模式。 |
| ISelectionItemProvider | 取決於 | 支援選取的清單專案控件必須實作 SelectionItem 控件模式。 這可讓清單專案控件在選取時傳達。 |
| IToggleProvider | 取決於 | 如果清單專案是可檢查的，而且動作不會執行選取狀態變更，則必須實作 [切換] 控件模式。 |
| IValueProvider | 取決於 | 如果可以編輯專案，則必須實作 值 控件模式。 清單專案控制件的變更會導致變更 UIA_NamePropertyId 和 UIA_ValueValuePropertyId 屬性的值。 |
必要事件
下表列出清單專案控制項需要支援的UI自動化事件。 如需事件的詳細資訊，請參閱 UI 自動化事件概觀。
| 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 子元素。
相關主題