Noções básicas da API JavaScript para OfficeUnderstanding the JavaScript API for Office

Este artigo fornece informações sobre a API JavaScript para Office e como usá-la. Para referenciar as informações, consulte API JavaScript para Office. Para obter informações sobre como atualizar os arquivos de projeto do Visual Studio para a versão mais recente da API JavaScript para Office, consulte Atualizar a versão da API JavaScript para Office e arquivos de esquema do manifesto.This article provides information about the JavaScript API for Office and how to use it. For reference information, see JavaScript API for Office. For information about updating Visual Studio project files to the most current version of the JavaScript API for Office, see Update the version of your JavaScript API for Office and manifest schema files.

Observação

Caso pretenda publicar o suplemento na experiência do Office depois de criá-lo, verifique se você está em conformidade com as Políticas de validação do AppSource. Por exemplo, para passar na validação, seu suplemento deve funcionar em todas as plataformas com suporte aos métodos que você definir (para mais informações, confira a seção 4.12 e a Página de hospedagem e disponibilidade de suplementos do Office).If you plan to publish your add-in to AppSource and make it available within the Office experience, make sure that you conform to the AppSource validation policies. For example, to pass validation, your add-in must work across all platforms that support the methods that you define (for more information, see section 4.12 and the Office Add-in host and availability page).

Fazer referência à biblioteca da API JavaScript para Office no suplementoReferencing the JavaScript API for Office library in your add-in

A biblioteca da API JavaScript para Office consiste no arquivo Office.js e nos arquivos .js específicos do aplicativo de host associado, como Excel-15.js e Outlook-15.js. O método mais simples de fazer referência à API é usando nossa CDN e adicionando o seguinte <script> à marca <head> da sua página:The JavaScript API for Office library consists of the Office.js file and associated host application-specific .js files, such as Excel-15.js and Outlook-15.js. The simplest method of referencing the API is using our CDN by adding the following <script> to your page's <head> tag:

<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>

Isso baixará e colocará os arquivos da API JavaScript para Office em cache quando o suplemento for carregado pela primeira vez a fim de garantir que o suplemento esteja usando a implementação mais recente do Office.js e de seus arquivos associados na versão especificada.This will download and cache the JavaScript API for Office files the first time your add-in loads to make sure that it is using the most up-to-date implementation of Office.js and its associated files for the specified version.

Para saber mais sobre a CDN do Office.js, inclusive como é feito o controle de versão e como lidar com a compatibilidade com versões anteriores, confira Fazendo referência à biblioteca da API JavaScript para Office na CDN (rede de distribuição de conteúdo).For more details around the Office.js CDN, including how versioning and backward compatibility is handled, see Referencing the JavaScript API for Office library from its content delivery network (CDN).

Inicialização do suplementoInitializing your add-in

Aplica-se a: todos os tipos de suplementosApplies to: All add-in types

Os Suplementos do Office têm sempre uma lógica de inicialização para fazer coisas como:Office Add-ins often have start-up logic to do things such as:

  • Verificar se a versão do Office do usuário será compatível com todas as APIs do Office chamadas pelo código.Check that the user's version of Office will support all the Office APIs that your code calls.

  • Garantir a existência de determinados artefatos, como uma planilha de nome específico.Ensure the existence of certain artifacts, such as worksheet with a specific name.

  • Solicitar ao usuário selecionar algumas células no Excel e inserir um gráfico inicializado com esses valores selecionados.Prompting the user to select some cells in Excel, and then inserting a chart initialized with those selected values.

  • Estabeleça associações.Establish bindings.

  • Usar a API de caixa de diálogo do Office para solicitar ao usuário definir valores de configurações padrão para o suplemento.Use the Office dialog API to prompt the user for default add-in settings values.

O código de inicialização só deverá chamar as APIs do Office.js quando a biblioteca estiver carregada.But your start-up code must not call any Office.js APIs until the library is loaded. Há duas maneiras pelas quais o código pode garantir que a biblioteca seja carregada.There are two ways that your code can ensure that the library is loaded. Elas estão descritas nas seções a seguir:They are described in the following sections:

Dica

Recomendamos que use Office.onReady()em vez deOffice.initialize.We recommend that you use Office.onReady() instead of Office.initialize. Embora Office.initialize ainda tenha suporte, usarOffice.onReady() oferece mais flexibilidade.Although Office.initialize is still supported, using Office.onReady() provides more flexibility. É 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.You can assign only one handler to Office.initialize and it's called only once by the Office infrastructure, but you can call Office.onReady() in different places in your code and use different callbacks.

Para saber mais sobre as diferenças entre essas técnicas, veja Principais diferenças entre Office.initialize e Office.onReady().For information about the differences in these techniques, see Major differences between Office.initialize and 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.For more details about the sequence of events when an add-in is initialized, see Loading the DOM and runtime environment.

Inicializar com o Office.onReady()Initialize with Office.onReady()

Office.onReady() é um método assíncrono que retorna um objeto Promise enquanto verifica se a biblioteca do Office.js está carregada.Office.onReady() is an asynchronous method that returns a Promise object while it checks to see if the Office.js library is loaded. Somente quando a biblioteca é carregada, ela resolve o Promise como um objeto que especifica o aplicativo host do Office com um valor de enumeração Office.HostType (Excel, Word etc.), e a plataforma com um valor de enumeração Office.PlatformType (PC, Mac, OfficeOnline etc.).When the library is loaded, it resolves the Promise as an object that specifies the Office host application with an Office.HostType enum value (Excel, Word, etc.) and the platform with an Office.PlatformType enum value (PC, Mac, OfficeOnline, etc.). O Promise será resolvido imediatamente quando a biblioteca estiver carregada aoOffice.onReady() ser chamada.The Promise resolves immediately if the library is already loaded when Office.onReady() is called.

Uma maneira de chamar Office.onReady() é passá-la por um método de retorno de chamada.One way to call Office.onReady() is to pass it a callback method. Exemplo:Here's an example:

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.Alternatively, you can chain a then() method to the call of Office.onReady(), instead of passing a callback. 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.For example, the following code checks to see that the user's version of Excel supports all the APIs that the add-in might call.

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.");
        }
    });

Este é o mesmo exemplo que usa as palavras-chave async e await em TypeScript:Here is the same example using the async and await keywords in 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 usando estruturas JavaScript adicionais que incluam testes e manipuladores próprios de inicialização, geralmente eles devem ser colocados dentro da resposta para Office.onReady().If you are using additional JavaScript frameworks that include their own initialization handler or tests, these should usually be placed within the response to Office.onReady(). Por exemplo, a função JQuery $(document).ready() seria referenciada da seguinte maneira:For example, JQuery's $(document).ready() function would be referenced as follows:

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

No entanto, há exceções a essa prática.However, there are exceptions to this practice. Por exemplo, digamos que você queira abrir o suplemento em um navegador (em vez de fazer sideload em um host do Office) para depurar a interface do usuário com ferramentas de navegador.For example, suppose you want to open your add-in in a browser (instead of sideload it in an Office host) in order to debug your UI with browser tools. Já que o Office.js não será carregado no navegador, onReady não será executado e o $(document).ready não será executado quando chamado dentro de onReady no Office.Since Office.js won't load in the browser, onReady won't run and the $(document).ready won't run if it's called inside the Office onReady. Outra exceção: você deseja que um indicador de progresso seja exibido no painel de tarefas enquanto o suplemento está sendo carregado.Another exception: you want a progress indicator to appear in the task pane while the add-in is loading. Nesse cenário, o código deve chamar ready da jQuery e usa a respectiva chamada de retorno para renderizar o indicador de progresso.In this scenario, your code should call the jQuery ready and use it's callback to render the progress indicator. Em seguida, a chamada de retorno do Office onReady pode substituir o indicador de progresso com a interface do usuário final.Then the Office onReady's callback can replace the progress indicator with the final UI.

Inicializar com Office.initializeInitialize with 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.An initialize event fires when the Office.js library is loaded and ready for user interaction. É possível atribuir um manipulador ao Office.initialize que implementa a lógica de inicialização.You can assign a handler to Office.initialize that implements your initialization logic. 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.The following is an example that checks to see that the user's version of Excel supports all the APIs that the add-in might call.

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 usando estruturas JavaScript adicionais que incluam testes e manipuladores próprios de inicialização, geralmente eles devem ser colocados dentro do evento Office.initialize.If you are using additional JavaScript frameworks that include their own initialization handler or tests, these should usually be placed within the Office.initialize event. No entanto, as exceções descritas anteriormente na seção Inicializar com Office.onReady() também se aplicam neste caso. Por exemplo, a função $(document).ready() do JQuery pode ser referenciada da seguinte maneira:(But the exceptions described in the Initialize with Office.onReady() section earlier apply in this case also.) For example, JQuery's $(document).ready() function would be referenced as follows:

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.For task pane and content add-ins, Office.initialize provides an additional reason parameter. Esse parâmetro especifica como um suplemento foi adicionado ao documento atual.This parameter specifies how an add-in was added to the current document. 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.You can use this to provide different logic for when an add-in is first inserted versus when it already existed within the document.

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.For more information, see Office.initialize Event and InitializationReason Enumeration.

Principais diferenças entre Office.initialize e Office.onReadyMajor differences between Office.initialize and 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.You can assign only one handler to Office.initialize and it's called only once by the Office infrastructure; but you can call Office.onReady() in different places in your code and use different callbacks. 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.For example, your code could call Office.onReady() as soon as your custom script loads with a callback that runs initialization logic; and your code could also have a button in the task pane, whose script calls Office.onReady() with a different callback. Quando isso ocorre, o segundo retorno de chamada é executado quando o botão é clicado.If so, the second callback runs when the button is clicked.

  • O evento Office.initialize é disparado no final do processo interno, e que o Office.js é inicializado automaticamente.The Office.initialize event fires at the end of the internal process in which Office.js initializes itself. Ele também é disparado imediatamente após o término do processo interno.And it fires immediately after the internal process ends. 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.If the code in which you assign a handler to the event executes too long after the event fires, then your handler doesn't run. 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.For example, if you are using the WebPack task manager, it might configure the add-in's home page to load polyfill files after it loads Office.js but before it loads your custom JavaScript. Quando o script carrega e atribui o manipulador, o evento de inicialização já ocorreu.By the time your script loads and assigns the handler, the initialize event has already happened. Mas nunca é "tarde demais" para chamar Office.onReady().But it is never "too late" to call Office.onReady(). Caso o evento de inicialização já tenha ocorrido, o retorno de chamada é executado imediatamente.If the initialize event has already happened, the callback runs immediately.

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.Even if you have no start-up logic, you should either call Office.onReady() or assign an empty function to Office.initialize when your add-in JavaScript loads. Algumas combinações de host e da plataforma do Office não carregam o painel de tarefas até uma das delas aconteça.Some Office host and platform combinations won't load the task pane until one of these happens. Os exemplos a seguir mostram essas duas abordagens.The following examples show these two approaches.

Office.onReady();
Office.initialize = function () {};

Modelo de objeto de API JavaScript para OfficeOffice JavaScript API object model

Depois de inicializado, o suplemento pode interagir com o host (por exemplo, o Excel ou o Outlook).Once initialized, the add-in can interact with the host (e.g. Excel, Outlook). A página Modelo de objeto de API JavaScript para Office tem mais detalhes sobre padrões de uso específicos.The Office JavaScript API object model page has more details on specific usage patterns. Há também documentação de referência detalhada para APIs Comuns e hosts específicos.There is also detailed reference documentation for both Common APIs and host-specific APIs.