Inicialize seu suplemento do Office

Os Suplementos do Office têm sempre uma lógica de inicialização para fazer coisas como:

• Verifique se a versão do Office do usuário dá suporte a todas as APIs do Office que seu código chama.

• Certifique-se da existência de determinados artefatos, como uma planilha com um nome específico.

• Solicite que o usuário selecione algumas células no Excel e insira um gráfico inicializado com esses valores selecionados.

• Estabeleça associações.

• Use a API de Caixa de Diálogo do Office para solicitar ao usuário os valores de configurações padrão do suplemento.

No entanto, um suplemento do Office não pode chamar com êxito nenhuma API JavaScript do Office até que a biblioteca tenha sido carregada. Este artigo descreve as duas maneiras pelas quais seu código pode garantir que a biblioteca foi carregada.

• Inicializar com Office.onReady().
• Inicializar com Office.initialize.

Para saber mais sobre a sequência de eventos na inicialização do suplemento, confira Carregar o ambiente de tempo de execução e o DOM.

Inicializar com o Office.onReady()

Office.onReady() é uma função assíncrona que retorna um objeto Promise enquanto verifica se a biblioteca Office.js está carregada. Quando a biblioteca é carregada, ela resolve a Promessa como um objeto que especifica o aplicativo cliente do Office com um Office.HostType valor de enumeração (Excel, Word, etc.) e a plataforma com um valor de Office.PlatformType enumeração (PC, Mac, OfficeOnline, etc.). O Promise será resolvido imediatamente quando a biblioteca estiver carregada aoOffice.onReady() ser chamada.

Uma maneira de chamar Office.onReady() é passar uma função de retorno de chamada. Veja um exemplo.

Office.onReady(function(info) {
    if (info.host === Office.HostType.Excel) {
        // Do Excel-specific initialization (for example, make add-in task pane's
        // appearance compatible with Excel "green").
    }
    if (info.platform === Office.PlatformType.PC) {
        // Make minor layout changes in the task pane.
    }
    console.log(`Office.js is now ready in ${info.host} on ${info.platform}`);
});

Como alternativa, é possível encadear um método then() à chamada de Office.onReady(), em vez de passar um retorno de chamada. Por exemplo, o código a seguir verifica se a versão do Excel do usuário é compatível com todas as APIs que o suplemento pode chamar.

Office.onReady()
    .then(function() {
        if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
            console.log("Sorry, this add-in only works with newer versions of Excel.");
        }
    });

Veja o mesmo exemplo usando as async palavras-chave e await no TypeScript.

(async () => {
    await Office.onReady();
    if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
        console.log("Sorry, this add-in only works with newer versions of Excel.");
    }
})();

Se você estiver usando estruturas JavaScript adicionais que incluem seu próprio manipulador de inicialização ou testes, eles geralmente devem ser colocados na resposta a Office.onReady(). Por exemplo, o método de$(document).ready() JQuery seria referenciado da seguinte maneira:

Office.onReady(function() {
    // Office is ready.
    $(document).ready(function () {
        // The document is ready.
    });
});

No entanto, há exceções a essa prática. Por exemplo, suponha que você queira abrir seu suplemento em um navegador (em vez de carregá-lo em um aplicativo do Office) para depurar a interface do usuário com ferramentas do navegador. Nesse cenário, uma vez que Office.js determina que está sendo executado fora de um aplicativo host do Office, ele chama o retorno de chamada e resolve a promessa com null para o host e a plataforma.

Outra exceção seria se você quiser que um indicador de progresso apareça no painel de tarefas enquanto o suplemento estiver sendo carregado. Nesse cenário, seu código deve chamar o jQuery ready e usar seu retorno de chamada para renderizar o indicador de progresso. Em seguida, o retorno de Office.onReady chamada pode substituir o indicador de progresso pela interface do usuário final.

Inicializar com Office.initialize

Um evento de inicialização é disparado quando a biblioteca do Office.js está carregada e pronta para a interação com o usuário. É possível atribuir um manipulador ao Office.initialize que implementa a lógica de inicialização. Veja a seguir um exemplo que verifica se a versão do Excel do usuário é compatível com todas as APIs que o suplemento pode chamar.

Office.initialize = function () {
    if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
        console.log("Sorry, this add-in only works with newer versions of Excel.");
    }
};

Se você estiver usando estruturas JavaScript adicionais que incluem seu próprio manipulador de inicialização ou testes, eles geralmente devem ser colocados dentro do Office.initialize evento (as exceções descritas na seção Inicializar com Office.onReady() anteriormente se aplicam a esse caso também). Por exemplo, o método de$(document).ready() JQuery seria referenciado da seguinte maneira:

Office.initialize = function () {
    // Office is ready.
    $(document).ready(function () {
        // The document is ready.
    });
  };

Para suplementos de conteúdo e painel de tarefas, Office.initialize fornece um parâmetro reason adicional. Esse parâmetro especifica como um suplemento foi adicionado ao documento atual. Você pode usar isso para fornecer uma lógica diferente para quando um suplemento é inserido pela primeira vez, em comparação com quando já existia dentro do documento.

Office.initialize = function (reason) {
    $(document).ready(function () {
        switch (reason) {
            case 'inserted': console.log('The add-in was just inserted.');
            case 'documentOpened': console.log('The add-in is already part of the document.');
        }
    });
 };

Para saber mais, veja Evento Office.initialize e Enumeração da InitializationReason.

Principais diferenças entre Office.initialize e Office.onReady

• É possível atribuir apenas um manipulador a Office.initialize, e ela é chamada apenas uma vez pela infraestrutura do Office, mas você pode chamar Office.onReady() em diferentes locais no código, e usar diferentes retornos de chamadas. Por exemplo, o código pode chamar Office.onReady(), logo que o script personalizado é carregado com um retorno de chamada que executa uma lógica de inicialização. Além disso, o código pode ter um botão no painel de tarefas, cujo script chama Office.onReady() com um retorno de chamada diferente. Quando isso ocorre, o segundo retorno de chamada é executado quando o botão é clicado.

• O evento Office.initialize é disparado no final do processo interno, e que o Office.js é inicializado automaticamente. Ele também é disparado imediatamente após o término do processo interno. Se o código no qual você atribui um manipulador ao evento for executado muito tempo após o evento ser disparado, então o manipulador não será executado. Por exemplo, se estiver usando o gerenciador de tarefas WebPack, ele poderá configurar a home page do suplemento para carregar arquivos de polyfill, após carregar o Office.js, mas antes de carregar o JavaScript personalizado. Quando o script carrega e atribui o manipulador, o evento de inicialização já ocorreu. Mas nunca é "tarde demais" para pagar Office.onReady(). Caso o evento de inicialização já tenha ocorrido, o retorno de chamada é executado imediatamente.

Office.onReady();

Office.initialize = function () {};

Depurar inicialização

Para obter informações sobre como depurar as Office.initialize funções and Office.onReady() , consulte Depurar as funções initialize e onReady.

Confira também

• Entendendo a API de JavaScript do Office
• Carregando o DOM e o ambiente de tempo de execução