Share via

Execute o código em seu Suplemento do Office quando o documento for aberto

  • Artigo

Importante

O runtime compartilhado só tem suporte em alguns aplicativos do Office. Para obter mais informações, confira Conjuntos de requisitos de tempo de execução compartilhados.

Você pode configurar o Suplemento do Office para carregar e executar o código assim que o documento for aberto. Isso será útil se você precisar registrar manipuladores de eventos, pré-carregar dados para o painel de tarefas, sincronizar a interface do usuário ou executar outras tarefas antes que o suplemento esteja visível.

Observação

A configuração é implementada com um método que seu código chama em runtime. Isso significa que o suplemento não será executado na primeira vez que um usuário abrir o documento. O suplemento deve ser aberto manualmente pela primeira vez em qualquer documento. Após a execução do método, no Office.initialize, office.onReady ou porque o usuário usa um caminho de código que o executa; em seguida, sempre que o documento é reaberto, o suplemento é carregado imediatamente e qualquer código no Office.initialize método ou Office.onReady é executado.

Observação

Este artigo exige que o suplemento do Office esteja configurado para usar um runtime compartilhado. Para obter mais informações, consulte Configurar seu Suplemento do Office para usar um runtime compartilhado.

Configurar seu suplemento para carregar quando o documento for aberto

O código a seguir configura seu suplemento para carregar e começar a ser executado quando o documento é aberto.

Office.addin.setStartupBehavior(Office.StartupBehavior.load);

Observação

O setStartupBehavior método é assíncrono.

Colocar código de inicialização no Office.initialize ou office.onReady

Quando o suplemento estiver configurado para carregar no documento aberto, ele será executado imediatamente. O Office.initialize manipulador de eventos será chamado. Coloque o código de inicialização no Office.initialize manipulador de eventos ou.Office.onReady

O código de suplemento do Excel a seguir mostra como registrar um manipulador de eventos para eventos de alteração da planilha ativa. Se você configurar o suplemento para carregar no documento aberto, esse código registrará o manipulador de eventos quando o documento for aberto. Você pode lidar com eventos de alteração antes que o painel de tarefas seja aberto.

// This is called as soon as the document opens.
// Put your startup code here.
Office.initialize = () => {
  // Add the event handler.
  Excel.run(async context => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    sheet.onChanged.add(onChange);

    await context.sync();
    console.log("A handler has been registered for the onChanged event.");
  });
};

/**
 * Handle the changed event from the worksheet.
 *
 * @param event The event information from Excel
 */
async function onChange(event) {
    await Excel.run(async (context) => {    
        await context.sync();
        console.log("Change type of event: " + event.changeType);
        console.log("Address of event: " + event.address);
        console.log("Source of event: " + event.source);
  });
}

O código de suplemento do PowerPoint a seguir mostra como registrar um manipulador de eventos para eventos de alteração de seleção do documento do PowerPoint. Se você configurar o suplemento para carregar no documento aberto, esse código registrará o manipulador de eventos quando o documento for aberto. Você pode lidar com eventos de alteração antes que o painel de tarefas seja aberto.

// This is called as soon as the document opens.
// Put your startup code here.
Office.onReady(info => {
  if (info.host === Office.HostType.PowerPoint) {
    Office.context.document.addHandlerAsync(Office.EventType.DocumentSelectionChanged, onChange);
    console.log("A handler has been registered for the onChanged event.");
  }
});

/**
 * Handle the changed event from the PowerPoint document.
 *
 * @param event The event information from PowerPoint
 */
async function onChange(event) {
  console.log("Change type of event: " + event.type);
}

Configurar o suplemento para nenhum comportamento de carga no documento aberto

Pode haver cenários em que você deseja desativar o comportamento de "executar no documento aberto". O código a seguir configura seu suplemento para não iniciar quando o documento é aberto. Em vez disso, ele começará quando o usuário o envolver de alguma forma, como escolher um botão de faixa de opções ou abrir o painel de tarefas. Esse código não terá efeito se o método não tiver sido chamado anteriormente no documento atual, com Office.StartupBehavior.load como o parâmetro.

Observação

Se o suplemento chamar o método, com Office.StartupBehavior.load como o parâmetro, em Office.initialize ou Office.onReady, o comportamento será ativado novamente. Portanto, nesse cenário, desativá-lo só se aplica à próxima vez que o documento for aberto, nem todas as aberturas subsequentes.

Office.addin.setStartupBehavior(Office.StartupBehavior.none);

Obter o comportamento de carga atual

Pode haver cenários em que seu suplemento precisa saber se ele está configurado para iniciar automaticamente na próxima vez que o documento atual for aberto. Para determinar qual é o comportamento de inicialização atual, execute o método a seguir, que retorna um valor Office.StartupBehavior .

let behavior = await Office.addin.getStartupBehavior();

Confira também