Conjuntos de requisitos de API JavaScript do Outlook

  • Artigo

Os suplementos do Outlook declaram quais versões de API elas exigem em seu manifesto. A marcação varia dependendo se você estiver usando o formato de manifesto XML ou o manifesto unificado do Microsoft 365.

A versão da API é especificada pela propriedade "extensions.requirements.capabilities". Defina a propriedade "capabilities.name" como "Caixa de Correio" e a propriedade "capabilities.minVersion" como o conjunto mínimo de requisitos de API que dá suporte aos cenários do suplemento.

Por exemplo, o trecho de código de manifesto a seguir indica um conjunto mínimo de requisitos de 1.1.

"extensions": [
{
  "requirements": {
    "capabilities": [
      {
        "name": "Mailbox", "minVersion": "1.1"
      }
    ]
  },
  ...
}

Todas as APIs do Outlook pertencem ao Mailboxconjunto de requisitos. O conjunto de requisitos Mailbox tem versões, e cada novo conjunto de APIs que lançamos pertence a uma versão superior. Nem todos os clientes do Outlook dão suporte ao mais novo conjunto de APIs, mas se um cliente do Outlook declarar suporte para um conjunto de requisitos, geralmente ele dá suporte a todas as APIs nesse conjunto de requisitos (marcar a documentação em uma API ou recurso específico para quaisquer exceções).

Configurando uma versão mínima do conjunto de requisitos nos controles de manifesto em que o cliente do Outlook o suplemento será exibido. Se um cliente não der suporte ao conjunto de requisitos mínimo, ele não carregará o suplemento. Por exemplo, se for especificada a versão 1.3 do conjunto de requisitos, significa que o suplemento não aparecerá nos clientes do Outlook incompatíveis com a versão 1.3.

Observação

Embora o Outlook no Android e no iOS dê suporte ao conjunto de requisitos 1.5, seu suplemento móvel agora pode implementar algumas APIs de conjuntos de requisitos posteriores. Para obter mais informações sobre quais APIs têm suporte no Outlook mobile, consulte APIs JavaScript do Outlook com suporte no Outlook em dispositivos móveis.

Usar APIs de conjuntos de requisitos posteriores

Definir um conjunto de requisitos não limita as APIs disponíveis que o suplemento pode usar. Por exemplo, se o suplemento especificar o conjunto de requisitos "Caixa de Correio 1.1", mas estiver em execução em um cliente do Outlook que dá suporte a "Caixa de Correio 1.3", o suplemento poderá usar APIs do conjunto de requisitos "Caixa de correio 1.3".

Para usar uma API mais recente, os desenvolvedores podem verificar se um determinado aplicativo oferece suporte ao conjunto de requisitos fazendo o seguinte:

if (Office.context.requirements.isSetSupported('Mailbox', '1.3')) {
  // Perform actions.
}
else {
  // Provide alternate flow/logic.
}

Como alternativa, os desenvolvedores podem verificar a existência de uma API mais recente usando a técnica JavaScript padrão.

if (item.somePropertyOrMethod !== undefined) {
  // Use item.somePropertyOrMethod.
  item.somePropertyOrMethod;
}

Nenhuma verificação desse tipo é necessária para qualquer API que esteja presente na versão do conjunto de requisitos especificada no manifesto.

Escolher um conjunto de requisitos mínimo

Os desenvolvedores devem usar o conjunto de requisitos mínimos que contém o conjunto essencial de APIs para seu cenário, sem o qual o suplemento não funcionará.

Conjuntos de requisitos suportados pelos Exchange Servers e clientes do Outlook

Nesta seção, vemos a gama de conjuntos de requisitos com suporte do Exchange Server e clientes do Outlook. Para obter detalhes sobre os requisitos de cliente e servidor para executar suplementos do Outlook, confira requisitos dos suplementos do Outlook.

Importante

Se o servidor Exchange de destino e o cliente do Outlook suportarem conjuntos de requisitos diferentes, então você estará restrito ao intervalo de conjunto de requisitos mais baixo. Por exemplo, se um suplemento estiver em execução no Outlook 2019 no Windows (conjunto de requisitos mais alto: 1,6) em relação ao Exchange 2016 (conjunto de requisitos mais alto: 1,5), seu suplemento poderá ser limitado ao requisito definido 1.5.

Suporte do Exchange Server

Os clientes a seguir oferecem suporte aos suplementos do Outlook.

Produto Versão Principal do Exchange Conjuntos de requisitos de API com suporte
Exchange Online Versão mais recente 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13
IdentityAPI 1.31
Exchange local2 2019 1.1, 1.2, 1.3, 1.4, 1.5
2016 1.1, 1.2, 1.3, 1.4, 1.5

Observação

1 Para exigir o conjunto de API de Identidade 1.3 no código de suplemento do Outlook, marcar se tiver suporte chamando isSetSupported('IdentityAPI', '1.3'). Não é permitido declará-lo no manifesto do suplemento do Outlook. Você também pode determinar se a API tem suporte, verificando se ela não é undefined. Para mais detalhes, confira Usar APIs de conjuntos de requisitos posteriores.

2 Mesmo que um suplemento implemente recursos de conjuntos de requisitos não compatíveis em um ambiente local do Exchange, ele ainda poderá ser adicionado a um cliente do Outlook, desde que o conjunto de requisitos especificado em seu manifesto se alinhe com aqueles com suporte do Exchange local. No entanto, um recurso implementado só funcionará se o cliente do Outlook no qual o suplemento estiver instalado der suporte ao conjunto de requisitos mínimo necessário por um recurso. Para determinar os conjuntos de requisitos compatíveis com diferentes clientes do Outlook, confira Suporte ao cliente do Outlook. Recomendamos complementar isso com a documentação do recurso específico para quaisquer exceções.

Suporte a cliente Outlook

Os suplementos são compatíveis com o Outlook nas seguintes plataformas.

Plataforma Versão Principal do Office/Outlook Conjuntos de requisitos de API com suporte
Navegador da Web12 interface do usuário moderna do Outlook quando conectado ao
Exchange Online: assinatura, Outlook.com		 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13
IdentityAPI 1.33
interface do usuário clássica do Outlook quando conectado ao
Exchange local		 1.1, 1.2, 1.3, 1.4, 1.5, 1.6
Windows novo Outlook no Windows (versão prévia) 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13
IdentityAPI 1.33
  • Assinatura do Microsoft 365
  • varejo perpétuo
 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.84, 1.94, 1.104, 1.114, 1.124, 1.134
IdentityAPI 1.33
OpenBrowserWindowApi 1.1
Outlook 2021 perpétuo licenciado por volume 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.84, 1.94
IdentityAPI 1.33
OpenBrowserWindowApi 1.1
Outlook 2019 perpétuo licenciado por volume 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7
Outlook 2016 perpétuo licenciado por volume 1.1, 1.2, 1.3, 1.45
Mac nova interface do usuário6 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13
IdentityAPI 1.33
OpenBrowserWindowApi 1.1
interface do usuário clássica 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8
IdentityAPI 1.33
OpenBrowserWindowApi 1.1
Android1 7 8 Assinatura 1.1, 1.2, 1.3, 1.4, 1.5
iOS1 7 8 Assinatura 1.1, 1.2, 1.3, 1.4, 1.5

Observação

1 Não há suporte para suplementos no Outlook no Android, no iOS e na Web móvel moderna com contas locais do Exchange. Determinados dispositivos iOS ainda dão suporte a suplementos ao usar contas locais do Exchange com Outlook na Web clássicos. Para obter informações sobre os dispositivos suportados, confira Requisitos para executar Suplementos do Office.

Dois suplementos não funcionam em Outlook na Web modernas em smartphones iPhone e Android. Para obter informações sobre os dispositivos suportados, confira Requisitos para executar Suplementos do Office.

3 Para exigir o conjunto de API de Identidade 1.3 no código de suplemento do Outlook, marcar se tiver suporte chamando isSetSupported('IdentityAPI', '1.3'). Não é permitido declará-lo no manifesto do suplemento do Outlook. Você também pode determinar se a API tem suporte, verificando se ela não é undefined. Para mais detalhes, confira Usar APIs de conjuntos de requisitos posteriores.

4 Suporte de versão para conjuntos de requisitos mais recentes no Outlook no Windows com uma assinatura do Microsoft 365 ou uma licença perpétua de varejo da seguinte maneira:

  • O suporte para 1.8 está disponível na versão 1910 (Build 12130.20272).
  • O suporte para 1.9 está disponível na versão 2008 (Build 13127.20296).
  • O suporte para 1.10 está disponível na versão 2104 (Build 13929.20296).
  • O suporte para 1.11 está disponível na versão 2110 (Build 14527.20226).
  • O suporte para 1.12 está disponível na versão 2206 (Build 15330.20196).
  • O suporte para 1.13 está disponível na versão 2304 (Build 16327.20248).

Para obter mais detalhes de acordo com sua versão, consulte a página de histórico de atualizações para Office 2021 ou Microsoft 365 e como encontrar a versão do cliente do Office e o canal de atualização.

5 O suporte para 1,4 no Outlook 2016 perpétuo licenciado por volume foi adicionado como parte da atualização de 3 de julho de 2018 para o Office 2016 (KB4022223).

6 O suporte para a nova interface do usuário do Mac está disponível no Outlook Versão 16.38.506. Para mais informações, consulte a seção Suporte de Suplemento no Outlook na nova Interface do Usuário do Mac.

7 Atualmente, há considerações adicionais ao projetar e implementar suplementos para clientes móveis. Para obter mais detalhes, confira considerações de código ao adicionar suporte para comandos de suplemento no Outlook em dispositivos móveis.

8 Embora o Outlook no Android e no iOS dê suporte ao conjunto de requisitos 1.5, seu suplemento móvel agora pode implementar algumas APIs de conjuntos de requisitos posteriores. Para obter mais informações sobre quais APIs têm suporte no Outlook mobile, consulte APIs JavaScript do Outlook com suporte no Outlook em dispositivos móveis.

Dica

É possível distinguir o Outlook clássico do moderno no navegador da Web, verificando sua barra de ferramentas da caixa de correio.

moderno

A barra de ferramentas moderna do Outlook.

clássico

A barra de ferramentas clássica do Outlook.

Referencie a biblioteca de produção da API JavaScript do Office

Para usar APIs em qualquer um dos conjuntos de requisitos numerados, você deve fazer referência à biblioteca de produção na rede de distribuição de conteúdo (CDN) do Office.js. Para obter informações sobre como usar APIs de visualização, consulte APIs de visualização de teste.

APIs de visualização de teste

As novas APIs do JavaScript para Outlook são introduzidas pela primeira vez na "visualização" e, posteriormente, tornam-se parte de um conjunto específico de requisitos numerados, após passarem por vários testes e após a recolha das opiniões de usuários. Para fornecer feedback sobre uma API de visualização, use o mecanismo de feedback no final da página da Web em que a API está documentada.

Observação

As APIs de visualização estão sujeitas a alterações e não são destinadas para uso em um ambiente de produção.

Para saber mais detalhes sobre as APIs de visualização, confira o artigo sobre o conjunto de requisitos da API de visualização do Outlook.