使用 IUIAutomationTextRange 存取及操作文字範圍

本主題描述如何使用 IUIAutomationTextRange 介面的屬性和方法，來存取及操作文字型控制項的文字內容。

什麼是文字範圍？

Microsoft 消費者介面自動化文字物件模型是以文字範圍的概念為基礎。 文字範圍是公開 IUIAutomationTextRange 介面的物件，代表以文字為基礎的控制項中的連續文字範圍。 每個文字範圍都有起始端點和結束端點，而且這兩個端點之間的所有文字內容都會被視為範圍的一部分。 其起始端點和結束端點位於相同位置的文字範圍，稱為 變質 (或空白) 文字範圍。 變質文字範圍可用來標記控制項文字內的特定位置，例如文字插入點的位置。

取得文字範圍物件

用戶端應用程式會使用 IUIAutomationTextPattern 介面的屬性和方法，取得文字範圍物件。 IUIAutomationTextRangePattern：:D ocumentRange屬性會擷取代表文字型控制項之整個文字內容的文字範圍，而其他方法則取得代表部分內容的文字範圍，例如選取的文字、可見文字或內嵌在文字中的物件。

IUIAutomationTextRangePattern：：GetVisibleRanges和GetSelection方法可以擷取文字範圍物件的陣列。 如果控制項部分被重迭的視窗或其他物件遮蔽， GetVisibleRanges 會傳回陣列，其中包含每個部分可見文字行的文字範圍物件。 同樣地，如果文字型控制項支援選取多個不連續的文字範圍， GetSelection 會傳回陣列，其中包含每個選取範圍的文字範圍物件。

IUIAutomationTextRangePattern：：RangeFromChild方法可讓用戶端應用程式擷取包含內嵌在文字內容中的物件的文字範圍。 用戶端會指定内嵌物件的 IUIAutomationElement 介面指標，例如影像、資料表或超連結，而 方法會傳回包含物件的文字範圍。 不過，如果内嵌物件沒有與其相關聯的文字，此方法會傳回變質的文字範圍。

用戶端應用程式可以使用 IUIAutomationTextRangePattern：：RangeFromPoint 方法來擷取最接近指定螢幕座標之可見文字或内嵌物件的文字範圍。

選取文字範圍內的文字

IUIAutomationTextRange介面包含一些方法，可讓用戶端應用程式控制文字型控制項中的文字選取範圍。

用戶端應用程式可以使用 IUIAutomationTextRange：：Select 方法來選取對應至文字範圍的文字，以及從文字控制項中移除先前的選取範圍。 以變質文字範圍呼叫 Select 會將插入點移至文字範圍的位置，而不選取任何文字。

如果控制項支援選取多個不連續的文字範圍，用戶端可以使用 IUIAutomationTextRange：：AddToSelection 和 RemoveFromSelection 方法，將文字範圍新增至選取的文字範圍，並從中移除這些範圍。 如果控制項一次只支援一個選取的文字範圍，但選取作業會導致選取多個不連續的文字範圍，則方法會傳回 E_INVALIDOPERATION 錯誤，或擴充或截斷目前的選取範圍。 用戶端應用程式可以藉由檢查 IUIAutomationTextPattern：：SupportedTextSelection 屬性，來探索控制項是否支援選取單一或多個文字範圍，或完全不支援。

如果文字型控制項支援文字插入，請在控制項中變質的文字範圍上呼叫 IUIAutomationTextRange：：AddToSelection 或 RemoveFromSelection 會移動插入點，但不會選取任何文字。

從文字範圍擷取文字

用戶端應用程式可以使用 IUIAutomationTextRange：：GetText 方法來擷取文字範圍的純文字。 純文字包含來源文字中找到的所有控制字元，例如歸位字元和 Unicode 由左至右標記 (LRM) 。 純文字不包含任何標記標記，例如可能存在於來源文字中的 HTML。 此外，來源文字中的任何逸出程式碼會轉換成純文字對等專案。 例如，「 會轉換成簡單的空白字元。

如果内嵌物件跨越文字範圍，則純文字會包含物件的內部文字，但非替代文字 (内嵌物件的名稱屬性) 。 如需詳細資訊，請參閱如何消費者介面自動化公開内嵌物件。

IUIAutomationTextRange：：FindText方法會搜尋特定字串的文字範圍，如果找到，則會傳回包含字串的新文字範圍。

從文字範圍擷取文字屬性

文字屬性會決定以文字為基礎的控制項中文字的格式設定樣式，並包含前景色彩、專案符號樣式、字型大小等專案。 消費者介面自動化支援許多文字屬性，並定義每個支援屬性的識別碼。 用戶端應用程式可以在呼叫 IUIAutomationTextRange：：GetAttributeValue 方法以及接收屬性值的 VARIANT 結構指標中指定屬性識別碼，以查詢特定文字屬性的文字範圍。 如需消費者介面自動化支援之每個文字屬性的詳細資訊，請參閱文字屬性識別碼。

GetAttributeValue所擷取的值代表整個文字範圍內的屬性值。 如果範圍中的所有文字都共用指定屬性的相同值， GetAttributeValue會傳回該值。 不過，如果屬性的值會隨著文字範圍而有所不同，GetAttributeValue會傳回名為ReservedMixedAttribute物件的靜態 Token 物件的IUnknown指標。 若要探索屬性的值是否因文字範圍而異，用戶端應用程式應該比較GetAttributeValue的結果與從IUIAutomation：：ReservedMixedAttributeValue屬性擷取的ReservedMixedAttribute物件。

不需要以文字為基礎的控制項，即可支援所有消費者介面自動化文字屬性。 如果用戶端呼叫 IUIAutomationTextRange：：GetAttributeValue 方法，並傳遞不支援屬性的識別碼，此方法會將 IUnknown 指標傳回至稱為 ReservedNotSupported 物件的靜態權杖物件。 若要探索是否支援特定屬性，用戶端應用程式應該比較GetAttributeValue的結果與從IUIAutomation：：ReservedNotSupportedValue屬性擷取的ReservedNotSupported物件。

用戶端應用程式可以使用 IUIAutomationTextRange：：FindAttribute 方法來搜尋具有特定文字屬性的文字範圍。 如果找到，此方法會傳回包含相符文字的新文字範圍。 請注意， FindAttribute 會傳回文字範圍，以便比對文字，即使文字不可見也一樣。

從文字範圍擷取内嵌物件

文字範圍可以包含內嵌的物件，例如資料表、影像、超連結等等。 用戶端應用程式可以藉由呼叫 IUIAutomationTextRange：：GetChildren 方法，擷取範圍中所有内嵌物件的集合。 與範圍重迭但未完全括住的内嵌物件也會包含在集合中。 如果範圍不包含内嵌物件， GetChildren 會擷取空的集合。

雖然這取決於以文字為基礎的控制項提供者， 但 GetChildren 方法通常不會傳回內嵌元素的任何子系。 例如，如果文字範圍包含具有許多子儲存格的資料表， GetChildren 方法通常會只傳回 table 元素，而不是儲存格元素。

基於效能或架構理由， GetChildren 可能無法擷取文字範圍內所有内嵌物件的 IUIAutomationElement 物件。 相反地，提供者可能會傳回包含虛擬化專案的集合。 如需詳細資訊，請參閱 使用虛擬化專案。

操作文字範圍

IUIAutomationTextRange介面提供數種方法，可用來操作和巡覽以文字為基礎的控制項中的文字範圍。 IUIAutomationTextRange：：Move、MoveEndpointByUnit和ExpandToEnclosingUnit方法會依指定的文字單位移動文字範圍或其中一個端點，例如字元、文字、段落等等。 如需詳細資訊，請參閱消費者介面自動化文字單位。

儘管其名稱， ExpandToEnclosingUnit 方法不一定會展開文字範圍。 相反地，它會藉由移動端點來「正規化」文字範圍，讓範圍完全包含指定的文字單位。 如果範圍小於指定的單位，則範圍會展開，如果大於指定的單位，則會縮短範圍。 下圖顯示 ExpandToEnclosingUnit 如何藉由移動範圍的端點來正規化文字範圍。

如果文字範圍從文字單位的開頭開始，並在下一個文字單位界限或之前結束，結束端點會移至下一個文字單位界限， (在上圖) 中看到 1 和 2。

如果文字範圍從文字單位的開頭開始，並在下一個單位界限結束，結束端點會停留在開始端點之後，或往後移動至下一個單位界限， (在上圖) 中看到 3 和 4。 如果開始端點與結束端點之間有多個文字單位界限，結束端點會在起始端點之後向後移動至下一個單位界限，導致長度為一個文字單位的文字範圍。

如果文字範圍從文字單位中間開始，則起始端點會向後移至文字單元的開頭，並視需要往前或向後移動結束端點到下一個單位界限， (上圖) 看到 5 到 8。

呼叫 IUIAutomationTextRange：：Move 方法時，提供者會依指定的文字單位將文字範圍正規化。 然後，提供者會以指定的文字單位數目往後或向前移動範圍。 移動範圍時，提供者會忽略文字中任何内嵌物件的界限。 不過， (單位界限本身可能會受到内嵌物件存在) 的影響。 下圖示范 Move 方法如何在内嵌物件和文字單位界限之間逐單位移動文字範圍。

IUIAutomationTextRange：：MoveEndpointByUnit方法會由指定的文字單位向前或向後移動其中一個端點。 下圖顯示端點向前移動的方式。

IUIAutomationTextRange：：MoveEndpointByRange方法可讓用戶端應用程式將文字範圍的一個端點設定為與第二個文字範圍的指定端點相同的位置。

將文字範圍捲動至檢視

IUIAutomationTextRange：：ScrollIntoView方法會捲動文字範圍，讓文字顯示在以文字為基礎的控制項檢視區中。 呼叫 ScrollIntoView時，用戶端可以指定文字是否應該與檢視區的頂端或底部對齊。

擷取文字範圍的封入專案

用戶端應用程式可以使用 IUIAutomationTextRange：：GetEnclosingElement 方法來擷取括文字範圍最內層元素的 IUIAutomation 介面指標。 封入專案通常是提供文字範圍的文字提供者。 不過，如果文字提供者支援資料表或超連結之類的子專案，封入元素可能是文字提供者的子系。

比較和複製文字範圍

IUIAutomationTextRange介面包含兩個比較文字範圍的方法。 IUIAutomationTextRange：：Compare方法會比較兩個文字範圍的開始和結束端點，如果兩個端點都相同，則會傳回TRUE。 IUIAutomationTextRange：：CompareEndpoints方法會比較兩個範圍的開始或結束端點。 如果端點相同，則傳回值為零，或是表示兩個端點相對位置的正值或負值。

用戶端應用程式可以使用 IUIAutomationTextRange：：Clone 方法來建立文字範圍的確切複本。 新的文字範圍可以獨立于原始文字範圍進行操作。

擷取批註

如果文字型控制項支援批註，文字範圍可以包含批註。 有許多不同的批註類型。 UIAutomationClient.h 標頭檔會定義一組具名常數值，識別消費者介面自動化支援的批註類型。 如需詳細資訊，請參閱 注釋類型識別碼。

某些類型的注釋是由支援 注釋 控制項模式的自動化元素所表示， (IUIAutomationAnnotationPattern 介面) 。 其他類型的注釋會透過 TextRange 控制項模式公開。 例如，提供者可以藉由讓IUIAutomationTextRange：：GetAttributeValue方法傳回AnnotationType_SpellingError的AnnotationTypes文字屬性，以及AnnotationObjects文字屬性的 Null 值，來公開簡單的拼字錯誤指標。

從文字範圍擷取注釋類型

您可以使用 IUIAutomationTextRange：：GetAttributeValue 方法，擷取文字範圍中存在的批註類型清單。 呼叫 方法時，請指定 UIA_AnnotationTypesAttributeId 的文字屬性識別碼，以及 VARIANT類型的參數指標。 當方法傳回時， VARIANT 參數會包含批註類型識別碼的清單，其中一個用於文字範圍中的每個批註類型。 如需詳細資訊，請參閱 注釋類型識別碼。

從文字範圍擷取所有批註

若要從文字範圍擷取批註，請呼叫 IUIAutomationTextRange：：GetAttributeValue 方法，並指定UIA_AnnotationObjectsAttributeId的文字屬性 識別碼，以及VARIANT類型的參數指標。 當方法傳回時， VARIANT 參數會包含 IUIAutomationElementArray 介面，代表自動化專案的陣列，一個用於文字範圍中的每個注釋。 IUIAutomationElementArray：：Length屬性會指出陣列中的元素數目，而IUIAutomationElementArray：：GetElement方法會擷取特定專案的IUIAutomationElement介面。

擷取特定批註的相關資訊

若要擷取特定注釋的相關資訊，請先擷取批註專案的 IUIAutomationElement 介面，如上一節所述。 接下來，藉由呼叫IUIAutomationElement：：GetCurrentPatternAs方法來擷取批註的IUIAutomationAnnotationPattern介面，其控制項模式識別碼為UIA_AnnotationPatternId、介面識別碼為 IID_IUIAutomationAnnotationPattern，以及接收批註IUIAutomationAnnotation指標的變數位址。 查詢 IUIAutomationAnnotation 介面的屬性，以擷取批註類型名稱和類型識別碼、注釋作者的名稱、批註的日期和時間，以及要標注之專案的 IUIAutomationElement 介面。

擷取批註目標文字

一般而言，注釋會套用至文字範圍中的一些文字子集。 擷取批註的 IUIAutomationElement 介面之後，您可以將介面傳遞至 IUIAutomationTextRange2：：RangeFromAnnotation 方法，以擷取包含批註目標文字的文字範圍。

擷取視覺化樣式

提供者會實作 樣式 控制項模式，以描述具有特定樣式、填滿色彩、填滿圖樣或圖案的 UI 元素。 這在描述檔中經常有這類樣式的專案時特別有用。 這類樣式通常會包含適用于殘障客戶的資訊;例如，樣式可以將特定字串描述為檔的標題，或將特定流程圖物件描述為菱形或圓形。

您可以使用 IUIAutomationTextRange：：GetAttributeValue 方法來擷取文字範圍中使用的視覺樣式名稱和識別碼。 使用 UIA_StyleNameAttributeId text 屬性來擷取樣式名稱， 並UIA_StyleIdAttributeId 擷取樣式識別碼。

支援視覺化樣式的文字型控制項可以實作 樣式 控制項模式，讓用戶端能夠存取控制項所使用的視覺化樣式相關資訊。 用戶端會透過 IUIAutomationStylesPattern 介面存取 Style 控制項模式。 您可以呼叫 IUIAutomationElement：：GetCurrentPattern 或 GetCurrentPatternAs 方法來擷取此介面，並將 UIA_StylesPatternId 指定為控制項模式識別碼。

IUIAutomationStylesPattern介面包含屬性和方法，可提供下列視覺樣式的相關資訊：

• 視覺化樣式的名稱，例如 「Normal」 或 「Heading 1」。
• 視覺樣式的識別碼。 如需詳細資訊，請參閱 樣式識別碼。
• 用來填滿文字型控制項的色彩。
• 用來填滿文字型控制項的圖樣色彩。
• 文字型控制項的形狀。
• 擴充屬性;也就是說，控制項特定的樣式名稱和值清單。

從文字範圍叫用操作功能表

從Windows 8.1開始，文字範圍可能支援IUIAutomationTextRange2介面。 此介面支援 ShowCoNtextMenu 方法。 您可以呼叫這個方法來叫用與文字範圍相關聯的任何操作功能表。 此案例是自動校正文字範圍或輸入法候選選取專案。 在這些情況下，會出現支援使用者互動的操作功能表。

相關主題

文字和 TextRange 控制項模式

文字內容的消費者介面自動化支援

使用文字型控制項