Configurar um documento para executar código quando ele for aberto

Você pode configurar seu 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 fique visível.

A configuração é implementada com um método que seu código chama em tempo de execução. 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. Depois que o método é executado, seja em Office.initialize, Office.onReady ou porque o usuário usa um caminho de código que o executa; Em seguida, sempre que o documento for reaberto, o suplemento será carregado imediatamente e qualquer código no Office.initialize método OR Office.onReady será executado.

Configurar o suplemento para ser carregado quando o documento for aberto

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

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

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

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

O seguinte código de suplemento do Excel mostra como registrar um manipulador de eventos para eventos de alteração da planilha ativa. Se você configurar seu suplemento para ser carregado ao abrir o documento, esse código registrará o manipulador de eventos quando o documento for aberto. Você pode manipular 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 seguinte código do suplemento do PowerPoint mostra como registrar um manipulador de eventos para eventos de alteração de seleção do documento do PowerPoint. Se você configurar seu suplemento para ser carregado ao abrir o documento, esse código registrará o manipulador de eventos quando o documento for aberto. Você pode manipular 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 seu suplemento para comportamento sem carregamento na abertura de documentos

Pode haver cenários em que você queira desativar o comportamento "executar ao abrir documento". O código a seguir configura o suplemento para não iniciar quando o documento é aberto. Em vez disso, ela será iniciada quando o usuário se envolver com ela de alguma forma, como escolher um botão da 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 parâmetro.

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

Obter o comportamento de carga atual

Pode haver cenários em que seu suplemento precise 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

• Configurar seu Suplemento do Office para usar um tempo de execução compartilhado
• Compartilhar dados e eventos entre funções personalizadas do Excel e tutorial do painel de tarefas
• Trabalhar com eventos usando a API JavaScript do Excel
• Runtimes em Suplementos do Office
• Gerenciando opções de confiança para Suplementos do Office