Compartilhar via

Trabalhar com eventos com a API JavaScript Word

Este artigo descreve conceitos importantes relacionados com o trabalho com eventos no Word e fornece exemplos de código que mostram como registar processadores de eventos, processar eventos e remover processadores de eventos com o Word API JavaScript.

Eventos no Word

Quando determinadas alterações ocorrem num documento Word, as notificações de eventos são acionadas. A Word APIs JavaScript permite-lhe registar processadores de eventos que permitem que o suplemento execute automaticamente funções designadas quando essas alterações ocorrem. Os eventos a seguir têm suporte no momento:

Evento Descrição Objetos com suporte Acionado durante a cocriação?
onAnnotationClicked Ocorre quando o utilizador seleciona uma anotação.

Objeto de dados de evento:
AnnotationClickedEventArgs		 Documento Não
onAnnotationHovered Ocorre quando o utilizador paira o cursor sobre uma anotação.

Objeto de dados de evento:
AnnotationHoveredEventArgs		 Documento Não
onAnnotationInserted Ocorre quando o utilizador adiciona uma ou mais anotações.

Objeto de dados de evento:
AnnotationInsertedEventArgs		 Documento Não
onAnnotationPopupAction Ocorre quando o utilizador executa uma ação num menu de pop-up de anotação.

Objeto de dados de evento:
AnnotationPopupActionEventArgs		 Documento Não
onAnnotationRemoved Ocorre quando o utilizador elimina uma ou mais anotações.

Objeto de dados de evento:
AnnotationRemovedEventArgs		 Documento Não
onContentControlAdded Ocorre quando é adicionado um controlo de conteúdo. Execute context.sync() no processador para obter as propriedades do novo controlo de conteúdo.

Objeto de dados de evento:
ContentControlAddedEventArgs		 Documento Sim
onDataChanged Ocorre quando os dados no controlo de conteúdo são alterados. Para obter o novo texto, carregue este controlo de conteúdo no processador. Para obter o texto antigo, não o carregue.

Objeto de dados de evento:
ContentControlDataChangedEventArgs		 ContentControl Sim
onDeleted Ocorre quando o controlo de conteúdo é eliminado. Não carregue este controlo de conteúdo no processador. Caso contrário, não conseguirá obter as respetivas propriedades originais.

Objeto de dados de evento:
ContentControlDeletedEventArgs		 ContentControl Sim
onEntered Ocorre quando o controlo de conteúdo é introduzido.

Objeto de dados de evento:
ContentControlEnteredEventArgs		 ContentControl Sim
onExited Ocorre quando o controlo de conteúdo é fechado, por exemplo, quando o cursor deixa o controlo de conteúdo.

Objeto de dados de evento:
ContentControlExitedEventArgs		 ContentControl Sim
onParagraphAdded Ocorre quando o utilizador adiciona novos parágrafos.

Objeto de dados de evento:
ParagraphAddedEventArgs		 Documento Sim
onParagraphChanged Ocorre quando o utilizador altera parágrafos.

Objeto de dados de evento:
ParagraphChangedEventArgs		 Documento Sim
onParagraphDeleted Ocorre quando o utilizador elimina parágrafos.

Objeto de dados de evento:
ParagraphDeletedEventArgs		 Documento Sim
onSelectionChanged Ocorre quando a seleção no controlo de conteúdo é alterada.

Objeto de dados de evento:
ContentControlSelectionChangedEventArgs		 ContentControl Sim

Eventos no modo de visualização

Observação

Os seguintes eventos estão disponíveis atualmente apenas na visualização pública. Para utilizar esta funcionalidade, tem de utilizar a versão de pré-visualização da biblioteca da API JavaScript do Office a partir da rede de entrega de conteúdos (CDN)Office.js. O arquivo de definição de tipo da compilação TypeScript e IntelliSense pode ser encontrado na CDN e DefinitelyTyped. Você pode instalar esses tipos com npm install --save-dev @types/office-js-preview.

Evento Descrição Objetos com suporte Acionado durante a cocriação?
onCommentAdded Ocorre quando são adicionados novos comentários.

Objeto de dados de evento:
CommentEventArgs		 Sim
onCommentChanged Ocorre quando um comentário ou a respetiva resposta é alterada.

Objeto de dados de evento:
CommentEventArgs		 Sim
onCommentDeleted Ocorre quando os comentários são eliminados.

Objeto de dados de evento:
CommentEventArgs		 Sim
onCommentDeselected Ocorre quando um comentário é desselecionado.

Objeto de dados de evento:
CommentEventArgs		 Sim
onCommentSelected Ocorre quando um comentário é selecionado.

Objeto de dados de evento:
CommentEventArgs		 Sim

Gatilhos de eventos

Os eventos num documento Word podem ser acionados por:

  • Interação do utilizador através do Word interface de utilizador (IU) que altera o documento.
  • Código do Suplemento do Office (JavaScript) que altera o documento.
  • Código do suplemento VBA (macro) que altera o documento.
  • Um cocriador que altera remotamente o documento com a IU Word ou o código do suplemento. Para obter mais informações, veja Eventos e cocriação.

Qualquer alteração que cumpra o comportamento predefinido de Word acionará os eventos correspondentes num documento.

Ciclo de vida de um manipulador de eventos

Um manipulador de eventos é criado quando um suplemento registra o manipulador de eventos. É destruído quando o suplemento anula o registo do processador de eventos ou quando o suplemento é atualizado, recarregado ou fechado. Os processadores de eventos não persistem como parte do ficheiro de Word ou entre sessões com Word na Web.

Eventos e coautoria

Com a cocriação, várias pessoas podem trabalhar em conjunto e editar o mesmo documento Word em simultâneo. Em eventos que podem ser disparados por um coautor, como onParagraphChanged, o objeto de evento respectivo conterá a propriedade fonte que indica se o evento foi acionado localmente pelo usuário atual (event.source == Local) ou pelo coautor remoto (event.source == Remote).

Os eventos que utilizam os seguintes objetos de dados são acionados durante a cocriação.

  • CommentEventArgs (visualização)
  • ContentControlAddedEventArgs
  • ContentControlDataChangedEventArgs
  • ContentControlDeletedEventArgs
  • ContentControlEnteredEventArgs
  • ContentControlExitedEventArgs
  • ContentControlSelectionChangedEventArgs
  • ParagraphAddedEventArgs
  • ParagraphChangedEventArgs
  • ParagraphDeletedEventArgs

Registrar um manipulador de eventos.

O seguinte exemplo de código regista um processador de eventos para o onParagraphChanged evento no documento. O código especifica que, quando o conteúdo é alterado no documento, a handleChange função é executada.

await Word.run(async (context) => {
    eventContext = context.document.onParagraphChanged.add(handleChange);

    await context.sync();
    console.log("Event handler successfully registered for onParagraphChanged event in the document.");
}).catch(errorHandlerFunction);

Como mostrado no exemplo anterior, quando você registrar um manipulador de eventos, indica a função a ser executada quando o evento especificado ocorre. Você pode criar essa função para executar as ações que seu cenário exige. O exemplo de código a seguir mostra uma função de manipulador de eventos que simplesmente grava informações sobre o evento no console.

async function handleChange(event) {
    await Word.run(async (context) => {
        await context.sync();        
        console.log("Type of event: " + event.type);
        console.log("Source of event: " + event.source);       
    }).catch(errorHandlerFunction);
}

Remover um manipulador de eventos

O exemplo de código seguinte regista um processador de eventos para o onParagraphChanged evento no documento e define a handleChange função que será executada quando o evento ocorrer. Também define a função deregisterEventHandler() que pode ser chamada posteriormente para remover aquele manipulador de eventos. Tenha em atenção que o RequestContext utilizado para criar o processador de eventos é necessário para removê-lo.

let eventContext;

async function registerEventHandler() {
  await Word.run(async (context) => {
    eventContext = context.document.onParagraphChanged.add(handleChange);

    await context.sync();
    console.log("Event handler successfully registered for onParagraphChanged event in the document.");
  });
}

async function handleChange(event: Word.ParagraphChangedEventArgs) {
  await Word.run(async (context) => {
    await context.sync();
    console.log(`${event.type} event was detected.`);
  });
}

async function deregisterEventHandler() {
  // The `RequestContext` used to create the event handler is needed to remove it.
  // In this example, `eventContext` is being used to keep track of that context.
  await Word.run(eventContext.context, async (context) => {
    eventContext.remove();
    await context.sync();
    
    eventContext = null;
    console.log("Removed event handler that was tracking content changes in paragraphs.");
  });
}

Utilizar .track()

Determinados tipos de eventos também requerem que chame track() o objeto ao qual está a adicionar o evento.

  • Eventos de controlo de conteúdo
    • onDataChanged
    • onDeleted
    • onEntered
    • onExited
    • onSelectionChanged
  • Eventos de comentários (pré-visualização)
    • onCommentAdded
    • onCommentChanged
    • onCommentDeleted
    • onCommentDeselected
    • onCommentSelected

O seguinte exemplo de código mostra como registar um processador de eventos em cada controlo de conteúdo. Uma vez que está a adicionar o evento aos controlos de conteúdo, track() é chamado em cada controlo de conteúdo na coleção.

let eventContexts = [];

await Word.run(async (context) => {
  const contentControls: Word.ContentControlCollection = context.document.contentControls;
  contentControls.load("items");
  await context.sync();

  // Register the onDeleted event handler on each content control.
  if (contentControls.items.length === 0) {
    console.log("There aren't any content controls in this document so can't register event handlers.");
  } else {
    for (let i = 0; i < contentControls.items.length; i++) {
      eventContexts[i] = contentControls.items[i].onDeleted.add(contentControlDeleted);

      // Call track() on each content control.
      contentControls.items[i].track();
    }

    await context.sync();

    console.log("Added event handlers for when content controls are deleted.");
  }
});

O seguinte exemplo de código mostra como registar processadores de eventos de comentários no objeto do corpo do documento e inclui uma body.track() chamada.

let eventContexts = [];

// Registers event handlers.
await Word.run(async (context) => {
  const body: Word.Body = context.document.body;

  // Track the body object since you're adding comment events to it.
  body.track();
  await context.sync();

  eventContexts[0] = body.onCommentAdded.add(onEventHandler);
  eventContexts[1] = body.onCommentChanged.add(onChangedHandler);
  eventContexts[2] = body.onCommentDeleted.add(onEventHandler);
  eventContexts[3] = body.onCommentDeselected.add(onEventHandler);
  eventContexts[4] = body.onCommentSelected.add(onEventHandler);
  await context.sync();

  console.log("Event handlers registered.");
});

Confira também