TextPatternRange.Move(TextUnit, Int32) 方法

定義

命名空間:

System.Windows.Automation.Text

組件:

UIAutomationClient.dll

將文字範圍移動指定的文字單元數。

public:
 int Move(System::Windows::Automation::Text::TextUnit unit, int count);

public int Move (System.Windows.Automation.Text.TextUnit unit, int count);

member this.Move : System.Windows.Automation.Text.TextUnit * int -> int

Public Function Move (unit As TextUnit, count As Integer) As Integer

參數

unit

TextUnit

文字單元界限。

count

Int32

要移動的文字單元數。 正值會將文字範圍向前移動，負值會將文字範圍向後移動，0 沒有作用。

傳回

Int32

實際移動的單元數。 如果新的文字範圍端點大於或小於 DocumentRange 端點，則此值會小於要求的數目。

範例

/// -------------------------------------------------------------------
/// <summary>
/// Starts the target application and returns the AutomationElement 
/// obtained from the targets window handle.
/// </summary>
/// <param name="exe">
/// The target application.
/// </param>
/// <param name="filename">
/// The text file to be opened in the target application
/// </param>
/// <returns>
/// An AutomationElement representing the target application.
/// </returns>
/// -------------------------------------------------------------------
private AutomationElement StartTarget(string exe, string filename)
{
    // Start text editor and load with a text file.
    Process p = Process.Start(exe, filename);

    // targetApp --> the root AutomationElement.
    AutomationElement targetApp =
        AutomationElement.FromHandle(p.MainWindowHandle);

    return targetApp;
}

''' -------------------------------------------------------------------
''' <summary>
''' Starts the target application and returns the AutomationElement 
''' obtained from the targets window handle.
''' </summary>
''' <param name="exe">
''' The target application.
''' </param>
''' <param name="filename">
''' The text file to be opened in the target application
''' </param>
''' <returns>
''' An AutomationElement representing the target application.
''' </returns>
''' -------------------------------------------------------------------
Private Function StartTarget( _
ByVal exe As String, ByVal filename As String) As AutomationElement
    ' Start text editor and load with a text file.
    Dim p As Process = Process.Start(exe, filename)

    ' targetApp --> the root AutomationElement.
    Dim targetApp As AutomationElement
    targetApp = AutomationElement.FromHandle(p.MainWindowHandle)

    Return targetApp
End Function

/// -------------------------------------------------------------------
/// <summary>
/// Obtain the text control of interest from the target application.
/// </summary>
/// <param name="targetApp">
/// The target application.
/// </param>
/// <returns>
/// An AutomationElement that represents a text provider..
/// </returns>
/// -------------------------------------------------------------------
private AutomationElement GetTextElement(AutomationElement targetApp)
{
    // The control type we're looking for; in this case 'Document'
    PropertyCondition cond1 =
        new PropertyCondition(
        AutomationElement.ControlTypeProperty,
        ControlType.Document);

    // The control pattern of interest; in this case 'TextPattern'.
    PropertyCondition cond2 = 
        new PropertyCondition(
        AutomationElement.IsTextPatternAvailableProperty, 
        true);

    AndCondition textCondition = new AndCondition(cond1, cond2);

    AutomationElement targetTextElement =
        targetApp.FindFirst(TreeScope.Descendants, textCondition);

    // If targetText is null then a suitable text control was not found.
    return targetTextElement;
}

''' -------------------------------------------------------------------
''' <summary>
''' Obtain the text control of interest from the target application.
''' </summary>
''' <param name="targetApp">
''' The target application.
''' </param>
''' <returns>
''' An AutomationElement. representing a text control.
''' </returns>
''' -------------------------------------------------------------------
Private Function GetTextElement(ByVal targetApp As AutomationElement) As AutomationElement
    ' The control type we're looking for; in this case 'Document'
    Dim cond1 As PropertyCondition = _
        New PropertyCondition( _
        AutomationElement.ControlTypeProperty, _
        ControlType.Document)

    ' The control pattern of interest; in this case 'TextPattern'.
    Dim cond2 As PropertyCondition = _
        New PropertyCondition( _
        AutomationElement.IsTextPatternAvailableProperty, _
        True)

    Dim textCondition As AndCondition = New AndCondition(cond1, cond2)

    Dim targetTextElement As AutomationElement = _
        targetApp.FindFirst(TreeScope.Descendants, textCondition)

    ' If targetText is null then a suitable text control was not found.
    Return targetTextElement
End Function

/// -------------------------------------------------------------------
/// <summary>
/// Moves a text range a specified number of text units. The text range 
/// is the current selection.
/// </summary>
/// <param name="targetTextElement">
/// The AutomationElment that represents a text control.
/// </param>
/// <param name="textUnit">
/// The text unit value.
/// </param>
/// <param name="units">
/// The number of text units to move.
/// </param>
/// <param name="direction">
/// Direction to move the text range. Valid values are -1, 0, 1.
/// </param>
/// <returns>
/// The number of text units actually moved. This can be less than the 
/// number requested if either of the new text range endpoints is 
/// greater than or less than the DocumentRange endpoints. 
/// </returns>
/// <remarks>
/// Moving the text range does not modify the text source in any way. 
/// Only the text range starting and ending endpoints are modified.
/// </remarks>
/// -------------------------------------------------------------------
private Int32 MoveSelection(
    AutomationElement targetTextElement, 
    TextUnit textUnit,
    int units,
    int direction)
{
    TextPattern textPattern =
        targetTextElement.GetCurrentPattern(TextPattern.Pattern) 
        as TextPattern;

    if (textPattern == null)
    {
        // Target control doesn't support TextPattern.
        return -1;
    }

    TextPatternRange[] currentSelection = textPattern.GetSelection();

    if (currentSelection.Length > 1)
    {
        // For this example, we cannot move more than one text range.
        return -1;
    }

    return currentSelection[0].Move(textUnit, Math.Sign(direction) * units);
}

''' -------------------------------------------------------------------
''' <summary>
''' Moves a text range a specified number of text units.
''' </summary>
''' <param name="targetTextElement">
''' The AutomationElement that represents a text control.
''' </param>
''' <param name="textUnit">
''' The text unit value.
''' </param>
''' <param name="units">
''' The number of text units to move.
''' </param>
''' <param name="direction">
''' Direction to move the text range. Valid values are -1, 0, 1.
''' </param>
''' <returns>
''' The number of text units actually moved. This can be less than the 
''' number requested if either of the new text range endpoints is 
''' greater than or less than the DocumentRange endpoints. 
''' </returns>
''' <remarks>
''' Moving the text range does not modify the text source in any way. 
''' Only the text range starting and ending endpoints are modified.
''' </remarks>
''' -------------------------------------------------------------------
Private Function MoveSelection( _
    ByVal targetTextElement As AutomationElement, _
    ByVal textUnit As TextUnit, _
    ByVal units As Integer, _
    ByVal direction As Integer) As Integer

    Dim textPattern As TextPattern = _
    DirectCast( _
    targetTextElement.GetCurrentPattern(textPattern.Pattern), _
    TextPattern)

    If (textPattern Is Nothing) Then
        ' Target control doesn't support TextPattern.
        Return -1
    End If

    Dim currentSelection As TextPatternRange() = _
    textPattern.GetSelection()

    If (currentSelection.Length > 1) Then
        ' For this example, we cannot move more than one text range.
        Return -1
    End If

    Return currentSelection(0).Move(textUnit, Math.Sign(direction) * units)
End Function

備註

如需周遊文字範圍的內容，則應在幕後執行一連串的步驟，才能成功執行 Move 方法。

1. 文字範圍已正規化；也就是，文字範圍已在 Start 端點摺疊為變質範圍，以致 End 端點變成多餘的。 在文字範圍跨越 unit 界限的情況下，必須移除模棱兩可的步驟;例如，“{The U}RL https://www.microsoft.com/ 內嵌在文字中”，其中 “{” 和 “}” 是文字範圍端點。

2. 結果產生的範圍會在 DocumentRange 中向後移至所要求 unit 界限的開頭。

3. 範圍會在 DocumentRange 中依所要求的 unit 界限數目向前或向後移動。

4. 範圍會接著依一個要求的 End 界限移動 unit 端點，從變質範圍狀態展開。

如何針對 Move() 和 ExpandToEnclosingUnit() 調整文字範圍的範例

在 UI 自動化樹狀結構的控制項檢視和內容檢視 (例如超連結或表格儲存格) 中，文字容器和內嵌物件的文字內容 (或內部文字) 會公開為單一連續的文字資料流； 物件界限會被忽略。 如果使用者介面自動化用戶端為了以某種方式進行敘述、解譯或分析而擷取文字，則應檢查特殊案例 (例如具有文字內容或其他內嵌物件的表格) 的文字範圍。 這可以藉由呼叫 GetChildren 來取得 AutomationElement 每個內嵌物件的 ，然後呼叫 RangeFromChild 以取得每個專案的文字範圍，以遞歸方式完成，直到擷取所有文字內容為止。

具有內嵌物件及其範圍的文字資料流範例

Move 會同時遵守隱藏和可見的文字。 使用者介面自動化 客戶端可以檢查IsHiddenAttribute文字可見性。

Move如果控件不支援指定的 TextUnit ，則會延遲至下一個最大TextUnit支援。

以下列出從最小單位到最大的順序。

• Character

• Format

• Word

• Line

• Paragraph

• Page

• Document

注意

文字不會以任何方式改變，因為文字範圍只會跨越文字的不同部分。

另請參閱

• TextPatternRangeEndpoint