注釋控制項模式

描述實作 IAnnotationProvider的指導方針和慣例，包括屬性和方法的相關資訊。 注釋控制項模式是用來公開檔中批 注 的屬性。

其中一個範例是批註批註方塊，位於檔的邊界，並連接到某些檔文字或試算表儲存格。

下圖顯示批註的範例。 如需實作此控制項模式的控制項範例，請參閱 控制項類型及其支援的控制項模式。

本主題包含下列各節。

• 實作方針和慣例
• IAnnotationProvider的必要成員
• 相關主題

實作方針和慣例

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

• 有許多不同的批註類型。 UIAutomationClient.h 標頭檔會定義一組具名常數值，以識別 Microsoft 消費者介面自動化支援的注釋類型。 如需詳細資訊，請參閱 注釋類型識別碼。
• 如果您使用 AnnotationType_Unknown，則必須實作 IAnnotationProvider：：AnnotationTypeName 屬性，讓用戶端能夠探索注釋類型的名稱。 您不需要實作標準批註類型的 AnnotationTypeName，因為消費者介面自動化提供預設名稱，但如果您需要覆寫預設名稱，則可以實作它。
• IAnnotationProvider：：Author屬性是選擇性的。
• IAnnotationProvider：:D ateTime屬性是選擇性的。
• IAnnotationProvider：：Target屬性是必要的，因為它會將批註連結到 UI 元素，讓用戶端能夠從批註巡覽回注釋所參考的 UI 元素。
• 因為注釋可以採用許多不同的形式， 所以 IAnnotationProvider 介面不會定義屬性來儲存注釋的值或文字。 簡單的注釋應該會公開IValueProvider 介面，而 IValueProvider：：Value屬性應該會傳回指定註解文字的唯讀值。 更豐富的注釋應該公開 ITextProvider 介面，以提供更豐富的文字給用戶端。
• 從 UI 元素巡覽至元素上的批註取決於要標注的專案種類，如下所示：
  • 如果是試算表儲存格，請實作 ISpreadsheetItemProvider：：GetAnnotationObjects 方法來參考批註。
  • 若為文字內容，請在ITextRangeProvider介面上實作AnnotationObjects text 屬性來參考批註。
• 某些種類的注釋不需要完整實作 IAnnotationProvider 介面。 例如，讓 ITextRangeProvider 介面傳回 AnnotationType_SpellingError 的 AnnotationTypes 文字 屬性，以及AnnotationObjects 文字屬性的 Null 值，即可表示簡單的拼字錯誤指標。
• 在看不到的 UI 元素上實作 IAnnotationProvider 介面會很有用。 例如，您可以建立實作IAnnotationProvider的非可見消費者介面自動化元素，以提供文法錯誤的擴充資訊。
• 如果控制項包含重迭的批註，則文字型控制項中的注釋可能會相當複雜。 使用下列指導方針來處理複雜的批註：
  • 沒有注釋的文字範圍應該會傳回 AnnotationTypes 文字屬性的空白陣列，以及 AnnotationObjects 文字屬性的空白陣列。
  • 具有一個注釋的文字範圍應該針對AnnotationTypes文字屬性傳回一個整數值的陣列，以及AnnotationObjects文字屬性的一個IRawElementProviderSimple介面陣列。
  • 具有多個批註的文字範圍應該針對AnnotationTypes文字屬性傳回多個整數值的陣列，以及AnnotationObjects文字屬性的相符IRawElementProviderSimple介面數目陣列。
  • 具有不同批註的文字範圍，例如批註和非註解文字的範圍，應該同時傳回AnnotationTypes 和AnnotationObjects的ReservedMixedAttributeValue屬性。 接收此回應的用戶端可以細分文字範圍，以尋找批註開始和結束的位置。

IAnnotationProvider的必要成員

實作 IAnnotationProvider 介面需要下列屬性。

必要成員	成員類型	備註
AnnotationTypeId	屬性	無。
AnnotationTypeName	屬性	無。
作者	屬性	無。
Datetime	屬性	無。
目標	屬性	無。

 

此控制項模式沒有任何相關聯的事件。

相關主題

控制項類型及其支援的控制項模式

UI 自動化控制項模式概觀

UI 自動化樹狀目錄概觀