實作 UI 自動化 Value 控制項模式

注意事項
這份文件適用於想要使用 System.Windows.Automation 命名空間中定義之 Managed UI Automation 類別的 .NET Framework 開發人員。如需 UI Automation 的最新資訊，請參閱 Windows Automation API：使用者介面自動化 (英文)。

本主題將介紹實作 IValueProvider 的方針和慣例，包括事件和屬性的相關資訊。其他參考的連結列於此主題的結尾部分。

ValuePattern 控制項模式是用來支援具有非跨範圍的內建值且可表示為字串的控制項。根據控制項及其設定，此字串可以編輯。如需實作此模式的控制項範例，請參閱 UI 自動化用戶端的控制項模式對應。

這個主題包含下列章節。

實作方針和慣例

實作 Value 控制項模式時，請注意下列方針和慣例：

如有任何項目的值可以編輯，ListItem 和 TreeItem 等控制項必須支援 ValuePattern，不論控制項目前的編輯模式為何。如果可以編輯子項目，則父控制項也必須支援 ValuePattern。

可編輯的清單項目範例

可編輯的清單項目。

單行編輯控制項會藉由實作 IValueProvider，支援以程式設計方式存取其內容。不過，多行編輯控制項不會實作 IValueProvider，而是藉由實作 ITextProvider，來提供內容的存取。
若要擷取多行編輯控制項的文字內容，控制項必須實作 ITextProvider。不過，ITextProvider 不支援設定控制項的值。
IValueProvider 不支援擷取格式資訊或子字串值。在這些情況下，請實作 ITextProvider。
像是 Microsoft Word 的 [色彩選擇器] 選擇控制項 (如下所示) 等控制項，必須支援 IValueProvider，這可支援色彩值 (例如「黃色」) 與對等內部 RGB 結構之間的字串對應。

色樣字串對應範例

已反白顯示黃色的色彩選擇器

控制項應先將其 IsEnabledProperty 設為 true，以及將其 IsReadOnlyProperty 設為 false，然後才允許呼叫 SetValue。

實作 IValueProvider 時需要使用下列屬性和方法。

提供者必須擲回下列例外狀況。

例外狀況類型	條件
InvalidOperationException	SetValue 如果地區設定特性資訊以不正確的格式傳遞給控制項，例如格式錯誤的日期。
ArgumentException	SetValue 新的值無法從字串轉換成控制項可辨認的格式。
ElementNotEnabledException	SetValue 當嘗試操作未啟用的控制項。