DataItem 控制項類型

發行項
06/13/2023

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

連絡人清單中的項目即是資料項目控制項的範例。資料項目控制項包含與使用者相關的資訊。由於包含更為豐富的資訊，這種控制項比簡單的清單項目複雜。

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

本主題包含下列各節。

一般樹狀結構
相關屬性
必要的控制項模式
在大型清單中使用 DataItems
必要的事件
DataItem 控制項類型範例
相關主題

一般樹狀結構

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

控制項檢視	內容檢視
DataItem 視情況而定 (0 個以上；可以結構化為階層)	DataItem 視情況而定 (0 個以上；可以結構化為階層)

資料格中資料項目 (Item) 的項目 (Element) 可裝載各種不同的物件，包括另一層資料項目，或是特定資料格項目 (Element) 如文字、影像或編輯控制項。如果資料項目專案具有特定的物件角色，則專案應該公開為特定控制項類型;例如，方格中可選取資料項目的 ListItem 控制項類型。

相關屬性

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

使用者介面自動化屬性	值	注意
UIA_AutomationIdPropertyId	請參閱備註。	此屬性的值在消費者介面自動化樹狀結構的原始檢視中的所有對等專案之間必須是唯一的。
UIA_BoundingRectanglePropertyId	請參閱備註。	包含整個控制項的最外層矩形。
UIA_ClickablePointPropertyId	請參閱備註。	如果有週框即受支援。如果周框內的每個點都不可點選，而且元素會執行特製化點擊測試，請覆寫並提供可點選的點。
UIA_ControlTypePropertyId	DataItem
UIA_IsContentElementPropertyId	true	資料項目控制項必須一律為內容。
UIA_IsControlElementPropertyId	true	資料項目控制項必須一律為控制項。
UIA_IsKeyboardFocusablePropertyId	請參閱備註。	如果控制項可接收鍵盤焦點，就必定支援此屬性。
UIA_ItemStatusPropertyId	請參閱備註。	如果控制項包含動態更新的狀態，則必須支援這個屬性，讓輔助技術可以在元素的狀態變更時收到更新。
UIA_ItemTypePropertyId	請參閱備註。	這個字串值可讓使用者知道項目所代表的物件為何。範例包括「媒體檔案」和「連絡人」。
UIA_LabeledByPropertyId	Null	資料項目控制項沒有靜態文字標籤。
UIA_LocalizedControlTypePropertyId	請參閱備註。	對應至 DataItem 控制項類型的當地語系化字串。 en-US 或英文 (美國) 的預設值為「data item」。
UIA_NamePropertyId	請參閱備註。	資料項目控制項一律包含使用者將辨識為專案識別碼的主要文字專案。

必要的控制項模式

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

控制項模式	支援	備註
IExpandCollapseProvider	相依	如果資料項目可以展開或折迭以顯示和隱藏資訊，則必須支援 ExpandCollapse 控制項模式。
IGridItemProvider	相依	當資料項目集合可在可空間巡覽的專案到專案的容器內使用時，資料項目將支援 GridItem 控制項模式。
IScrollItemProvider	相依	當資料容器的資料容器具有超過螢幕可以容納的專案時，所有資料項目都支援使用 ScrollItem 控制項模式捲動到檢視。
ISelectionItemProvider	相依	選取資料項目的能力取決於內容。
ITableItemProvider	相依	如果資料項目包含在具有標頭元素的 DataGrid 控制項類型內，它應該支援 TableItem 控制項模式。
IToggleProvider	相依	如果資料項目包含可迴圈的狀態，它應該支援切換控制項模式。
IValueProvider	相依	如果資料項目的主要文字是可編輯的，則必須支援值控制項模式。

在大型清單中使用 DataItems

由於大型清單通常會在 UI 架構內虛擬化以協助效能，因此消費者介面自動化用戶端無法使用消費者介面自動化查詢功能，以與其他專案容器中相同的方式搜尋完整樹狀結構的內容。用戶端應該將專案捲動至檢視 (或展開控制項，以顯示所有可用的選項，) ，再從資料項目存取完整的資訊集。

在資料項目的消費者介面自動化元素上呼叫SetFocus時，Microsoft Windows 檔案總管會成功傳回，並讓焦點設定為數據項子樹內的 [編輯] 控制項。

必要的事件

下表列出資料項目控制項需要支援消費者介面自動化事件。如需 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 控制項模式，它必須支援這個事件。