Word.RangeCollection class

Pacote:

word

Contém uma coleção do Word. Range objetos.

Extends

OfficeExtension.ClientObject

Comentários

Conjunto de APIs: WordApi 1.1

Usada por

• Word. Corpo: pesquisar
• Word. ContentControl: getTextRanges, search, split
• Word. Document: grammaticalErrors, search, spellingErrors, storyRanges
• Word. Parágrafo: getTextRanges, search, split
• Word. Intervalo: getHyperlinkRanges, getTextRanges, search, split
• Word. Tabela: pesquisar
• Word. TableRow: search

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/25-paragraph/search.yaml

// Does a basic text search and highlights matches in the document.
await Word.run(async (context) => {
  const results : Word.RangeCollection = context.document.body.search("extend");
  results.load("length");

  await context.sync();

  // Let's traverse the search results and highlight matches.
  for (let i = 0; i < results.items.length; i++) {
    results.items[i].font.highlightColor = "yellow";
  }

  await context.sync();
});

Propriedades

context	O contexto de solicitação associado ao objeto. Isso conecta o processo do suplemento ao processo do aplicativo host do Office.
items	Obtém os itens filhos carregados nesta coleção.

Métodos

getFirst()	Obtém o primeiro intervalo nesta coleção. Lançará um ItemNotFound erro se essa coleção estiver vazia.
getFirstOrNullObject()	Obtém o primeiro intervalo nesta coleção. Se essa coleção estiver vazia, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte métodos e propriedades *OrNullObject.
load(options)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.
load(propertyNames)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.
load(propertyNamesAndPaths)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.
toJSON()	Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é passado para JSON.stringify(). (JSON.stringify, por sua vez, chama o toJSON método do objeto que é passado para ele.) Enquanto o objeto original Word.RangeCollection é um objeto API, o toJSON método retorna um objeto JavaScript simples (digitado como Word.Interfaces.RangeCollectionData) que contém uma matriz "items" com cópias superficiais de todas as propriedades carregadas dos itens da coleção.
track()	Acompanha o objeto para ajuste automático com base nas alterações adjacentes no documento. Essa chamada é uma abreviação de context.trackedObjects.add(thisObject). Se você estiver usando esse objeto entre .sync chamadas e fora da execução sequencial de um lote ".run" e receber um erro "InvalidObjectPath" ao definir uma propriedade ou invocar um método no objeto, precisará adicionar o objeto à coleção de objetos rastreados quando o objeto foi criado pela primeira vez. Se esse objeto fizer parte de uma coleção, você também deverá acompanhar a coleção pai.
untrack()	Libere a memória associada a este objeto, se ele já tiver sido rastreado anteriormente. Essa chamada é a forma abreviada de context.trackedObjects.remove(thisObject). Ter muitos objetos rastreados desacelera o aplicativo host, por isso, lembre-se de liberar todos os objetos adicionados após usá-los. Você precisará ligar context.sync() antes que a liberação de memória entre em vigor.

Detalhes da propriedade

context

O contexto de solicitação associado ao objeto. Isso conecta o processo do suplemento ao processo do aplicativo host do Office.

context: RequestContext;

Valor da propriedade

Word.RequestContext

items

Obtém os itens filhos carregados nesta coleção.

readonly items: Word.Range[];

Valor da propriedade

Word.Range[]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/25-paragraph/get-paragraph-on-insertion-point.yaml

// Gets complete sentences from the insertion point to the end of its paragraph.
await Word.run(async (context) => {
  const selection: Word.Range = context.document.getSelection();
  const sentences: Word.RangeCollection = selection.getTextRanges(["."], false);
  sentences.load("$none");
  await context.sync();

  const firstSentence: Word.Range = sentences.items[0];
  const paragraphEnd: Word.Range = selection.paragraphs.getFirst().getRange(Word.RangeLocation.end);
  const remainingRange: Word.Range = firstSentence.expandTo(paragraphEnd);
  const sentencesToTheEndOfParagraph: Word.RangeCollection = remainingRange.getTextRanges(["."], false);
  sentencesToTheEndOfParagraph.load("text");
  await context.sync();

  console.log("Sentences from the current sentence to the paragraph end:");
  for (let i = 0; i < sentencesToTheEndOfParagraph.items.length; i++) {
    console.log(sentencesToTheEndOfParagraph.items[i].text);
  }
});

Detalhes do método

getFirst()

Obtém o primeiro intervalo nesta coleção. Lançará um ItemNotFound erro se essa coleção estiver vazia.

getFirst(): Word.Range;

Retornos

Word.Range

Comentários

Conjunto de APIs: WordApi 1.3

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-tracked-changes.yaml

// Replaces the document body and tracks text and formatting edits.
await Word.run(async (context) => {
  const document: Word.Document = context.document;
  const body: Word.Body = document.body;

  document.changeTrackingMode = Word.ChangeTrackingMode.off;
  body.clear();
  body.insertParagraph("The quick brown fox jumps over the lazy dog.", Word.InsertLocation.start);
  await context.sync();

  document.changeTrackingMode = Word.ChangeTrackingMode.trackAll;
  await context.sync();

  const adjective: Word.Range = body.search("quick").getFirst();
  const animal: Word.Range = body.search("fox").getFirst();
  const ending: Word.Range = body.search("dog").getFirst();
  adjective.insertText("swift", Word.InsertLocation.replace);
  animal.delete();
  ending.insertText("hound", Word.InsertLocation.replace);
  const description: Word.Range = body.search("lazy").getFirst();
  description.font.bold = true;
  await context.sync();

  document.changeTrackingMode = Word.ChangeTrackingMode.off;
  await context.sync();

  console.log("Created tracked text edits and applied bold formatting.");
});

getFirstOrNullObject()

Obtém o primeiro intervalo nesta coleção. Se essa coleção estiver vazia, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte métodos e propriedades *OrNullObject.

getFirstOrNullObject(): Word.Range;

Retornos

Word.Range

Comentários

Conjunto de APIs: WordApi 1.3

load(options)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(options?: Word.Interfaces.RangeCollectionLoadOptions & Word.Interfaces.CollectionLoadOptions): Word.RangeCollection;

Parâmetros

options

Word.Interfaces.RangeCollectionLoadOptions & Word.Interfaces.CollectionLoadOptions

Fornece opções para quais propriedades do objeto devem ser carregadas.

Retornos

Word.RangeCollection

load(propertyNames)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(propertyNames?: string | string[]): Word.RangeCollection;

Parâmetros

propertyNames

string | string[]

Uma cadeia de caracteres delimitada por vírgula ou uma matriz de cadeias de caracteres que especifica as propriedades a serem carregadas.

Retornos

Word.RangeCollection

load(propertyNamesAndPaths)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Word.RangeCollection;

Parâmetros

propertyNamesAndPaths

OfficeExtension.LoadOption

propertyNamesAndPaths.select é uma cadeia de caracteres delimitada por vírgula que especifica as propriedades a serem carregadas e propertyNamesAndPaths.expand é uma cadeia de caracteres delimitada por vírgula que especifica as propriedades de navegação a serem carregadas.

Retornos

Word.RangeCollection

toJSON()

Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é passado para JSON.stringify(). (JSON.stringify, por sua vez, chama o toJSON método do objeto que é passado para ele.) Enquanto o objeto original Word.RangeCollection é um objeto API, o toJSON método retorna um objeto JavaScript simples (digitado como Word.Interfaces.RangeCollectionData) que contém uma matriz "items" com cópias superficiais de todas as propriedades carregadas dos itens da coleção.

toJSON(): Word.Interfaces.RangeCollectionData;

Retornos

Word.Interfaces.RangeCollectionData

track()

Acompanha o objeto para ajuste automático com base nas alterações adjacentes no documento. Essa chamada é uma abreviação de context.trackedObjects.add(thisObject). Se você estiver usando esse objeto entre .sync chamadas e fora da execução sequencial de um lote ".run" e receber um erro "InvalidObjectPath" ao definir uma propriedade ou invocar um método no objeto, precisará adicionar o objeto à coleção de objetos rastreados quando o objeto foi criado pela primeira vez. Se esse objeto fizer parte de uma coleção, você também deverá acompanhar a coleção pai.

track(): Word.RangeCollection;

Retornos

Word.RangeCollection

untrack()

Libere a memória associada a este objeto, se ele já tiver sido rastreado anteriormente. Essa chamada é a forma abreviada de context.trackedObjects.remove(thisObject). Ter muitos objetos rastreados desacelera o aplicativo host, por isso, lembre-se de liberar todos os objetos adicionados após usá-los. Você precisará ligar context.sync() antes que a liberação de memória entre em vigor.

untrack(): Word.RangeCollection;

Retornos

Word.RangeCollection