Trabalhar com objetos Range

Uma tarefa comum ao usar Visual Basic é especificar uma área em um documento e fazer algo com ele, como inserir texto ou aplicar formatação. Por exemplo, talvez você deseje escrever uma macro que localize uma palavra ou frase dentro de uma parte de um documento. A parte do documento pode ser representada por um objeto Range. Após o objeto Range ser identificado, métodos e propriedades do objeto Range podem ser aplicados para modificar o conteúdo do intervalo.

Um objeto Range refere-se a uma área contígua de um documento. Cada objeto Range é definido por uma posição de caractere inicial e final. Tal como os indicadores são usados em um documento, os objetos Range são usados em procedimentos do Visual Basic para identificar partes específicas de um documento. Um objeto Range pode ser tão pequeno quanto o ponto de inserção ou tão grande quanto o documento inteiro. Entretanto, ao contrário de um indicador, um objeto Range existirá somente enquanto o procedimento que o definiu estiver sendo executado.

As propriedades Start, End e StoryType identificam exclusivamente um objeto Range. As propriedades Start e End retornam ou definem as posições de caractere inicial ou final do objeto Range. A posição de caractere no início do documento é zero, a posição após o primeiro caractere é um e assim por diante. Há vários tipos de história representados pelas constantes WdStoryType da propriedade StoryType.

Observação

Os objetos Range são independentes da seleção. Ou seja, você pode definir e modificar um intervalo sem alterar a seleção atual. Você também pode definir vários intervalos em um documento, mas só pode haver uma seleção por painel de documento.

Usando o método Range

Use o método Range do objeto Document para criar um objeto Range localizado no texto principal e tenha um determinado ponto de extremidade e início. O exemplo a seguir cria um objeto Range que começa no início do primeiro caractere e se estende até o décimo caractere.

Sub SetNewRange() 
 Dim rngDoc As Range 
 Set rngDoc = ActiveDocument.Range(Start:=0, End:=10) 
End Sub

Você pode ver que o objeto Range é criado ao aplicar uma propriedade ou método ao objeto Range. Por exemplo, o código a seguir aplica formatação com negrito aos dez primeiros caracteres do documento ativo.

Sub SetBoldRange() 
 Dim rngDoc As Range 
 Set rngDoc = ActiveDocument.Range(Start:=0, End:=10) 
 rngDoc.Bold = True 
End Sub

Quando precisar fazer referência a um objeto Range várias vezes, você poderá usar a instrução Set para definir uma variável como sendo igual ao objeto Range. Entretanto, se só precisar efetuar uma única ação em um objeto Range, não há necessidade de armazenar o objeto em uma variável. O mesmo resultado pode ser obtido usando apenas uma instrução que identifica o intervalo e altera a propriedade Bold.

Sub BoldRange() 
 ActiveDocument.Range(Start:=0, End:=10).Bold = True 
End Sub

Como um indicador, um intervalo pode abranger um grupo de caracteres ou marcar um local em um documento. O objeto Range do exemplo seguinte tem os mesmos pontos inicial e final. O intervalo não inclui texto algum. O exemplo a seguir insere texto no início do documento ativo.

Sub InsertTextBeforeRange() 
 Dim rngDoc As Range 
 Set rngDoc = ActiveDocument.Range(Start:=0, End:=0) 
 rngDoc.InsertBefore "Hello " 
End Sub

Você pode definir os pontos de início e de extremidade de um intervalo usando os números de posição do caractere, conforme mostrado acima, ou usar as propriedades Start e End com objetos como Selection, Bookmark ou Range. O exemplo a seguir cria um objeto Range começando no início do segundo parágrafo e terminando após o terceiro parágrafo.

Sub NewRange() 
 Dim doc As Document 
 Dim rngDoc As Range 
 
 Set doc = ActiveDocument 
 Set rngDoc = doc.Range(Start:=doc.Paragraphs(2).Range.Start, _ 
 End:=doc.Paragraphs(3).Range.End) 
End Sub

Para obter informações adicionais e exemplos, consulte o método Range.

Usando a propriedade Range

A propriedade Range aparece em vários objetos, como Paragraph, Bookmark e Cell, e é usada para retornar um objeto Range. O exemplo a seguir retorna um objeto Range que se refere ao primeiro parágrafo do documento ativo.

Sub SetParagraphRange() 
 Dim rngParagraph As Range 
 Set rngParagraph = ActiveDocument.Paragraphs(1).Range 
End Sub

Após ter um objeto Range, você pode usar qualquer de suas propriedades e métodos para modificar o objeto Range. O exemplo a seguir seleciona o segundo parágrafo do documento ativo.

Sub FormatRange() 
 ActiveDocument.Paragraphs(2).Range.Select 
 Selection.ParagraphFormat.Alignment = wdAlignParagraphCenter 
End Sub

Se você precisar aplicar várias propriedades ou métodos ao mesmo objeto Range, poderá usar a estrutura With…End With. O exemplo a seguir formata o texto do primeiro parágrafo do documento ativo.

Sub FormatFirstParagraph() 
 Dim rngParagraph As Range 
 Set rngParagraph = ActiveDocument.Paragraphs(1).Range 
 With rngParagraph 
 .Bold = True 
 .ParagraphFormat.Alignment = wdAlignParagraphCenter 
 With .Font 
 .Name = "Stencil" 
 .Size = 15 
 End With 
 End With 
End Sub

Para obter informações adicionais e exemplos, consulte o tópico da propriedade Range.

Redefinir um objeto Range

Use o método SetRange para redefinir um objeto Range existente. O exemplo a seguir define um intervalo como a seleção atual. O método SetRange redefine o intervalo para que se refira à seleção atual mais os 10 caracteres seguintes.

Sub ExpandRange() 
 Dim rngParagraph As Range 
 Set rngParagraph = Selection.Range 
 rngParagraph.SetRange Start:=rngParagraph.Start, _ 
 End:=rngParagraph.End + 10 
End Sub

Para obter informações e exemplos adicionais, consulte o método Range para o Documento.

Observação

Ao depurar suas macros, você pode usar o método Select para garantir que um objeto Range está se referindo ao intervalo correto de texto. Por exemplo, o seguinte seleciona um objeto Range que se refere ao segundo e terceiro parágrafos do documento ativo e formatará a fonte da seleção.

Sub SelectRange() 
 Dim rngParagraph As Range 
 
 Set rngParagraph = ActiveDocument.Paragraphs(2).Range 
 
 rngParagraph.SetRange Start:=rngParagraph.Start, _ 
 End:=ActiveDocument.Paragraphs(3).Range.End 
 rngParagraph.Select 
 
 Selection.Font.Italic = True 
End Sub

Suporte e comentários

Tem dúvidas ou quer enviar comentários sobre o VBA para Office ou sobre esta documentação? Confira Suporte e comentários sobre o VBA para Office a fim de obter orientação sobre as maneiras pelas quais você pode receber suporte e fornecer comentários.