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 utilizador suporta todas as APIs do Office que o seu código chama.

• Confirme a existência de determinados artefactos, como uma folha de cálculo com um nome específico.

• Peça ao utilizador para selecionar algumas células no Excel e, em seguida, insira um gráfico inicializado com esses valores selecionados.

• Estabeleça associações.

• Utilize a API de Caixa de Diálogo do Office para pedir ao utilizador valores de definições de suplemento predefinidos.

No entanto, um Suplemento do Office não pode chamar com êxito nenhuma APIs javaScript do Office até que a biblioteca tenha sido carregada. Este artigo descreve as duas formas de o seu código garantir que a biblioteca foi carregada.

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

Dica

Recomendamos que use Office.onReady()em vez deOffice.initialize. Embora Office.initialize ainda seja suportado, Office.onReady() proporciona mais flexibilidade. Só pode atribuir um processador a Office.initialize e este é chamado apenas uma vez pela infraestrutura do Office. Pode chamar Office.onReady() em locais diferentes no seu código e utilizar chamadas de retorno diferentes.

Para saber mais sobre as diferenças entre essas técnicas, veja Principais diferenças entre Office.initialize e Office.onReady().

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 devolve um objeto Promise enquanto verifica se a biblioteca Office.js está carregada. Quando a biblioteca é carregada, resolve a promessa como um objeto que especifica a aplicação cliente do Office com um valor de enumeração Office.HostType (Excel, , Wordetc.) e a plataforma com um valor de enumeração Office.PlatformType (PC, Mac, OfficeOnline, etc.). O Promise será resolvido imediatamente quando a biblioteca estiver carregada aoOffice.onReady() ser chamada.

Uma forma de chamar Office.onReady() é transmitir-lhe uma função de chamada de retorno. 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.");
        }
    });

Eis o mesmo exemplo que utiliza as async palavras-chave e await em 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 estiver a utilizar arquiteturas JavaScript adicionais que incluam o seu próprio processador ou testes de inicialização, estes devem normalmente ser colocados na resposta a Office.onReady(). Por exemplo, o método de$(document).ready() JQuery seria referenciado da seguinte forma:

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 pretende abrir o seu suplemento num browser (em vez de o carregar lateralmente numa aplicação do Office) para depurar a sua IU com ferramentas do browser. Neste cenário, assim que Office.js determinar que está em execução fora de uma aplicação anfitriã do Office, chamará a chamada de retorno e resolverá a promessa com null para o anfitrião e a plataforma.

Outra exceção seria se quisesse que um indicador de progresso fosse apresentado no painel de tarefas enquanto o suplemento está a ser carregado. Neste cenário, o código deve chamar o jQuery e utilizar a chamada de ready retorno para compor o indicador de progresso. Em seguida, a Office.onReady chamada de retorno pode substituir o indicador de progresso pela IU 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 estiver a utilizar arquiteturas JavaScript adicionais que incluam o seu próprio processador ou testes de inicialização, estas devem normalmente ser colocadas no Office.initialize evento (as exceções descritas na secção Inicializar com o Office.onReady() aplicam-se anteriormente também neste caso). Por exemplo, o método de$(document).ready() JQuery seria referenciado da seguinte forma:

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 ligar Office.onReady(). Caso o evento de inicialização já tenha ocorrido, o retorno de chamada é executado imediatamente.

Observação

Mesmo que não tenha uma lógica de inicialização, você deve atribuir ou chamar Office.onReady() uma função vazia para Office.initialize quando o JavaScript do suplemento for carregado. Algumas combinações de aplicações e plataformas do Office não carregarão o painel de tarefas até que uma destas ações aconteça. Os exemplos a seguir mostram essas duas abordagens.

Office.onReady();

Office.initialize = function () {};

Depurar inicialização

Para obter informações sobre a depuração das Office.initialize funções e Office.onReady() , veja 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