Text 和 TextRange 控制項模式
描述實作ITextProvider、ITextProvider2和ITextRangeProvider的指導方針和慣例，包括屬性和方法的相關資訊。 文字控制項模式可讓應用程式和控制項公開簡單的文字物件模型，讓用戶端可從文字型控制項擷取文字內容、文字屬性和内嵌物件。
為了支援 文字 控制項模式，控制項會實作 ITextProvider 和 ITextProvider2 介面。 支援 文字 控制項模式的控制項類型包括 [編輯 ] 和 [ 檔 ] 控制項類型，以及可讓使用者輸入文字或選取唯讀文字的任何其他控制項類型。
文字控制項模式可以與其他 Microsoft 消費者介面自動化控制項模式搭配使用，以支援文字中數種類型的内嵌物件，包括資料表、超連結和命令按鈕。
ITextProvider和ITextProvider2介面包含許多取得文字範圍的方法。 文字範圍是物件，代表文字容器中的連續文字範圍或多個不連續的文字範圍。 一個 ITextProvider 方法會取得代表整份檔的文字範圍，而其他方法則取得代表檔部分的文字範圍，例如選取的文字、可見文字或內嵌在文字中的物件。
文字範圍物件是由 TextRange 控制項模式表示，該模式是透過 ITextRangeProvider 介面實 作。 TextRange控制項模式提供方法和屬性，用來公開範圍中文字的相關資訊、移動範圍的端點、選取或取消選取文字、將範圍捲動到檢視中等等。
如需Text和TextRange控制項模式的詳細資訊，請參閱消費者介面自動化文字內容的支援。
從 Windows 8.1 提供者開始，可以實作ITextRangeProvider2介面。 這可叫用與文字範圍相關聯的操作功能表。 這支援文字自動校正或輸入法編輯器 (輸入法) 候選選取等案例。
本主題包含下列各節。
實作方針和慣例
實作 文字 控制項模式時，請注意下列指導方針和慣例：
- 例如，允許存取文字 (的任何控制項，輸入文字或選取唯讀文字) 應該支援 文字 控制項模式。
- 文字控制項模式可以搭配任何 UI 元素使用，這些 UI 元素會呈現文字，甚至是標準按鈕控制項上的靜態標籤。 不過，在無法選取或沒有插入點的靜態文字控制項上並不需要它。
- 為了確保文字可以完全存取，實作 ITextProvider 的 控制項也應該支援 IValueProvider 介面。 IValueProvider 藉由提供變更文字的程式設計方式來補充 ITextProvider 。 它也提供與輔助技術用戶端應用程式更高的相容性，包括以舊版技術為基礎的技術，例如 Microsoft Active Accessibility。 實作這兩種控制項模式時，TextChanged事件 (UIA_Text_TextChangedEventId) 和AutomationPropertyChanged事件 (UIA_AutomationPropertyChangedEventId) 相當於Value屬性 (UIA_ValueValuePropertyId) 。 這兩個事件都必須受到支援。
- 文字控制項模式僅支援一個文字資料流程，以及每個控制項一個檢視區。 如果應用程式在窗格中提供多個檔檢視，則每個檢視 (控制項) 應該獨立支援 ITextProvider 。
- ITextProvider：：GetSelection方法可能會傳回代表目前選取文字的單一文字範圍。 如果控制項支援選取多個非連續文字範圍， GetSelection 方法應該會傳回陣列，其中包含每個選取文字範圍的一個 ITextRangeProvider 介面。
- Text控制項模式會將插入點表示為空白) 文字範圍的變質 (。 當插入點存在且未選取任何文字時， ITextProvider：：GetSelection 方法應該會傳回變質的文字範圍。 如需詳細資訊，請參閱 與系統插入號的互通性。
- 如果檢視區中可見連續的文字範圍， ITextProvider：：GetVisibleRanges 方法可能會傳回單一文字範圍，或者可能會傳回代表多個部分可見文字行的脫離文字範圍陣列。
- 如果子項目不包含任何文字， ITextProvider：：RangeFromChild 方法應該會傳回變質的範圍。 因為内嵌物件可以包含文字， 所以 RangeFromChild 方法不一定會傳回變質的文字範圍。 如需詳細資訊，請參閱如何消費者介面自動化公開内嵌物件。
- ITextProvider：：RangeFromPoint方法會使用指定的螢幕座標，在檔區域中執行點擊測試。 產生的文字範圍應該與插入點或選取範圍一致，因為按一下指定螢幕座標的位置。 例如，如果影像位於指定的螢幕座標，產生的文字範圍應該與 ITextProvider：：RangeFromChild 方法為影像取得的文字範圍相同。 同樣地，如果用戶端應用程式要求系統插入號中央位置的文字範圍 (插入點) ，產生的文字範圍應該與系統插入號位置相同。
- ITextProvider：:D ocumentRange屬性應該一律提供文字範圍，其中包含對應ITextProvider實作支援的所有文字。
- UIA_Text_TextChangedEventId 事件必須在 發生任何文字變更之後引發，即使檢視區中看不到變更也一樣。 例如，即使使用者將完全相同的文字貼到選取的文字上，提供者也應該引發 事件。
- 每當選取文字時，或每當插入點 (插入點) 在文字之間移動時 ，都必須引發 UIA_Text_TextSelectionChangedEventId。
實作 TextRange 控制項模式時，請注意下列指導方針和慣例：
- 不論文字的可見度狀態為何， TextRange 控制項模式的所有方法都應該執行文字作業。 文字範圍的可見度一律可以藉由查詢 IsHidden text 屬性 (UIA_IsHiddenAttributeId) 來決定。
- 可能的話，提供者應該確保任何文字變更，例如刪除、插入和移動，會反映在 ITextRangeProvider 介面實例 (相關聯的文字範圍物件中，) 並引發 UIA_Text_TextChangedEventId 事件。 用戶端可以使用 事件做為提示，以確認對控制項文字所做的編輯變更。
- ITextRangeProvider：：Compare、CompareEndpoints和MoveEndpointByRange方法所使用的所有文字範圍物件都必須是相同文字控制項模式實作的對等。
- 雖然並非必要，但 ITextRangeProvider：：CompareEndpoints方法所擷取的pRetVal值可以指出兩個端點之間的 (TextUnit_Character TextUnit_Character) 之間的距離。 不過，用戶端應用程式不應該相依于 pRetVal 的精確度超出其正值或負值。
- ITextRangeProvider：：ExpandToEnclosingUnit、Move和MoveEndpointByUnit方法需要仔細考慮指定的文字單位。 如需詳細資訊，請參閱操作 TextRange by Text Unit。
- 如需 與 ITextRangeProvider：：Select、 AddToSelection和 RemoveFromSelection 方法相關的實作需求，請參閱在文字範圍內選取文字。
- ITextRangeProvider：：FindText和FindAttribute方法會向前或向後搜尋單一相符的文字字串或文字屬性。 如果找不到相符專案，它們應該會傳回 Null 。
- ITextRangeProvider：：GetAttributeValue方法必須傳回從UiaGetReservedMixedAttributeValue或UiaGetReservedNotSupportedValue函式取得的位址，如果相關屬性在範圍中不同，或是文字控制項不支援該屬性。 TextRange控制項模式規格不允許加入新的文字屬性識別碼，或變更現有屬性的定義方式。
- 可能的話， ITextRangeProvider：：GetBoundingRectangles 方法應該會傳回陣列，其中包含文字範圍中每個完整或部分可見文字行的一個周框。 如果無法這樣做，提供者可以傳回陣列，該陣列只包含完全可見線條的周框;不過，這會限制用戶端應用程式能夠精確地描述在螢幕上呈現文字的方式。
- ITextRangeProvider：：GetChildren方法應該會傳回內嵌在文字範圍中的所有子專案，但不需要傳回子項目的任何子系。 例如，如果文字範圍包含具有許多子儲存格的資料表， GetChildren 方法可能會只傳回 table 元素，而不是儲存格元素。 基於效能或架構理由，提供者可能無法公開自動化樹狀結構中檔內裝載的所有内嵌物件。 在此情況下，提供者至少應該支援透過 GetChildren 方法列舉子物件，而且作為選項，支援 VirtualizedItem 控制項模式以支援虛擬化支援。
- ITextRangeProvider：：GetEnclosingElement方法通常會傳回提供文字範圍的文字提供者。 不過，如果文字提供者支援資料表或超連結之類的子物件，封入專案可能是文字提供者的子系。 GetEnclosingElement傳回的專案應該是最接近指定文字範圍的專案。 例如，如果文字範圍位於表格的儲存格中， GetEnclosingElement 應該傳回包含的儲存格，而不是 table 元素。
- ITextRangeProvider：：GetText方法應該會傳回範圍內的純文字。 如需詳細資訊，請參閱從文字範圍取得文字。
- 呼叫 ITextRangeProvider：：ScrollIntoView 應該對齊 alignToTop 參數所指定之文字控制項檢視區中的文字。 雖然水準對齊沒有需求，但文字範圍應該同時以水準和垂直方式顯示。 評估 alignToTop 參數時，提供者必須考慮文字控制項的方向和文字的流程方向。 例如，如果 alignToTop 是 TRUE ，則垂直導向的文字控制項包含從右至左流動的文字，提供者應該將文字範圍與檢視區右側對齊。
- 透過 TextUnit_Line移動檔時，如果文字範圍進入內嵌表格，則儲存格中的每個文字行都應該視為一行。
ITextProvider的必要成員
實作 ITextProvider 介面需要下列屬性和方法。
| 必要成員 | 成員類型 | 備註 |
|---|---|---|
| DocumentRange | 屬性 | 無 |
| SupportedTextSelection | 屬性 | 無 |
| GetSelection | 方法 | 無 |
| GetVisibleRanges | 方法 | 無 |
| RangeFromChild | 方法 | 無 |
| RangeFromPoint | 方法 | 無 |
| UIA_Text_TextChangedEventId | 事件 | 無 |
| UIA_Text_TextSelectionChangedEventId | 事件 | 無 |
實作 ITextProvider2 介面需要下列其他屬性和方法。
| 必要成員 | 成員類型 | 備註 |
|---|---|---|
| GetCaretRange | 方法 | 無 |
| RangeFromAnnotation | 方法 | 無 |
ITextRangeProvider的必要成員
實作 ITextRangeProvider 介面需要下列屬性和方法。
| 必要成員 | 成員類型 | 備註 |
|---|---|---|
| AddToSelection | 方法 | 無 |
| 複製 | 方法 | 無 |
| 比較 | 方法 | 無 |
| CompareEndpoints | 方法 | 無 |
| ExpandToEnclosingUnit | 方法 | 無 |
| FindAttribute | 方法 | 無 |
| FindText | 方法 | 無 |
| GetAttributeValue | 方法 | 無 |
| GetBoundingRectangles | 方法 | 無 |
| GetChildren | 方法 | 無 |
| GetEnclosingElement | 方法 | 無 |
| GetText | 方法 | 無 |
| 移動 | 方法 | 無 |
| MoveEndpointByUnit | 方法 | 無 |
| MoveEndpointByRange | 方法 | 無 |
| 選取 | 方法 | 無 |
| ScrollIntoView | 方法 | 無 |
實作 ITextRangeProvider2 介面需要下列其他屬性和方法。
| 必要成員 | 成員類型 | 備註 |
|---|---|---|
| ShowContextMenu | 方法 | See "Implementing ShowContextMenu" section |
TextRange控制項模式沒有相關聯的事件。
支援文字範圍
本節描述提供者如何實作 ITextRangeProvider 和 ITextRangeProvider2 介面的各種方法，以支援 TextRange 控制項模式。
依文字單位操作文字範圍
ITextRangeProvider介面提供數種方法，可用來操作和巡覽文字型控制項中的文字範圍。 ITextRangeProvider：：Move、MoveEndpointByUnit和ExpandToEnclosingUnit方法會依指定的文字單位移動文字範圍或其中一個端點，例如字元、文字、段落等等。 如需詳細資訊，請參閱消費者介面自動化文字單位。
儘管其名稱為何， ITextRangeProvider：：ExpandToEnclosingUnit 方法不一定會展開文字範圍。 相反地，它會藉由移動端點來「正規化」文字範圍，讓範圍包含指定的文字單位。 如果範圍小於指定的單位，則範圍會展開，或者如果超過指定的單位，則會縮短範圍。 ExpandToEnclosingUnit方法一律以一致的方式正規化文字範圍非常重要;否則，文字單位所操作文字範圍的其他層面將無法預期。 下圖顯示 ExpandToEnclosingUnit 如何移動範圍的端點來正規化文字範圍。
如果文字範圍從文字單位的開頭開始，並在開頭或之前結束，下一個文字單位界限，則結束端點會移至下一個文字單位界限， (上圖) 中看到 1 和 2。
如果文字範圍從文字單位的開頭開始，並在下一個單位界限結束之後，結束端點會維持或往後移動至下一個單位界限， (上圖) 看到上圖中的 3 和 4。 如果開始端點與結束端點之間有多個文字單位界限，則結束端點會在開始端點之後向後移至下一個單位界限，導致長度為一個文字單位的文字範圍。
如果文字範圍是從文字單位中間開始，則起始端點會往後移至文字單位的開頭，而結束端點會視需要往前或往後移動至下一個單位界限， (上圖) 看到上圖中的 5 到 8。
呼叫 ITextRangeProvider：：Move 方法時，提供者會使用 與 ExpandToEnclosingUnit 方法相同的正規化邏輯，依指定的文字單位正規化文字範圍。 然後，提供者會依指定的文字單位數目向後或向前移動範圍。 移動範圍時，提供者應該忽略文字中任何内嵌物件的界限。 不過， (，單位界限本身可能會受到内嵌物件存在) 的影響。 下圖示范 Move 方法如何跨内嵌物件和文字單位界限移動文字範圍、單位單位。
ITextRangeProvider：：MoveEndpointByUnit方法會由指定的文字單位向前或向後移動其中一個端點，如下圖所示。
ITextRangeProvider：：MoveEndpointByRange方法可讓用戶端應用程式將文字範圍的一個端點設定為與第二個文字範圍的指定端點相同的位置。
選取文字範圍中的文字
ITextRangeProvider介面包含數種方法，可用來控制文字型控制項中的文字選取範圍。
ITextRangeProvider：：Select方法應該選取對應至文字範圍的文字，並從文字控制項中移除先前的選取範圍。 如果在變質文字範圍上呼叫 Select ，提供者應該將插入點移至文字範圍的位置，而不選取任何文字。
如果控制項支援選取多個不連續的文字範圍， 則 ITextRangeProvider：：AddToSelection 和 RemoveFromSelection 方法會新增文字範圍，並將其從選取的文字範圍集合中移除。 如果控制項一次只支援一個選取的文字範圍，但選取作業會導致選取多個不連續的文字範圍，提供者應該傳回 E_INVALIDOPERATION 錯誤，或應該擴充或截斷目前的選取範圍。 ITextProvider：：SupportedTextSelection屬性應該指出控制項是否支援選取單一或多個文字範圍，或完全不支援。
如果文字型控制項支援文字插入，請在控制項中反產生的文字範圍上呼叫 ITextRangeProvider：：AddToSelection 或 RemoveFromSelection 應該移動插入點，但不應該選取任何文字。
從文字範圍取得文字
ITextRangeProvider：：GetText方法應該會傳回文字範圍的純文字。 純文字應該包含來源文字中找到的所有控制字元，例如歸位字元和 Unicode (LRM) 。 純文字不應包含任何標記標記，例如可能存在於來源文字中的 HTML。 此外，源文字中的任何逸出碼都應該轉換成純文字對等專案。 例如，「 應該轉換成簡單的空白字元。
如果内嵌物件跨越文字範圍，純文字應該包含物件的內部文字，但不是替代文字 (内嵌物件的名稱屬性) ，因為它可能與描述性內部文字不一致。 如需詳細資訊，請參閱如何消費者介面自動化公開内嵌物件。
實作 ShowCoNtextMenu
ITextRangeProvider2：：ShowCoNtextMenu 應該一律在範圍的起點顯示操作功能表。 這應該相當於使用者按下快顯功能表鍵或 SHIFT + F10，並在範圍開頭加上插入點時，會發生什麼事。
如果顯示操作功能表通常會導致插入點移至指定位置，則它應該以程式設計方式叫用ShowCoNtextMenu以支援消費者介面自動化。
與系統插入號的互通性
正確支援插入點對許多用戶端應用程式至關重要，包括不是以消費者介面自動化為基礎的用戶端應用程式。 在 [文字 ] 控制項模式中，插入點是以系統插入號位置的空) 文字範圍 (變質來表示。 當插入點移動時，控制項應該引發 TextSelectionChanged 事件 (UIA_Text_TextSelectionChangedEventId) 。 某些用戶端應用程式相依于此事件來監視插入點的位置，以及追蹤文字選取範圍。
當控制項包含選取的文字時， 文字 控制項模式的目前設計不會提供方法，讓您直接將插入點的位置與特定文字範圍產生關聯。 提供者必須追蹤文字選取範圍，並適當地設定插入點的位置。 由於選取文字通常是藉由在按住 SHIFT 鍵或 CTRL 鍵時移動插入點來完成，或者兩者都可以在選取範圍變更時檢查這些索引鍵的狀態來追蹤文字選取範圍。
由於協助工具架構可為系統插入號提供內建支援，但不會支援自訂插入號，因此文字型控制項應該盡可能使用系統插入號。 使用自訂插入號的控制項可以建立與自訂插入號相同的維度的系統插入號，並將系統插入號放在控制項 UI 中與自訂插入號相同的位置，以確保插入號可存取插入點。 或者，使用自訂插入號的控制項可以實作 Microsoft Active Accessibility provider for OBJID_CARET ，直接為自訂插入號提供協助工具資訊。
如需系統插入號的詳細資訊，請參閱 插入號。
若要測試控制項是否正確公開系統插入號的位置，請使用 檢查 和 可存取的事件監看員 工具。
系統插入號點陣圖中央的螢幕座標應該一律符合插入點的位置。 如此一來，用戶端就可以在 ITextProvider：：RangeFromPoint 的呼叫中使用插入號畫面座標來擷取正確代表插入點位置的文字範圍。
相關主題