Compartilhar via

Especificar requisitos da API e de aplicativos do Office

  • Artigo

O seu Suplemento do Office pode depender de uma aplicação específica do Office (também denominada anfitrião do Office) ou de membros específicos da API JavaScript do Office (office.js). Por exemplo, o suplemento pode:

  • Executar em um único aplicativo do Office (por exemplo, Word ou Excel) ou diversos aplicativos.
  • Utilize as APIs JavaScript do Office que só estão disponíveis em algumas versões do Office. Por exemplo, a versão perpétua licenciada em volume do Excel 2016 não suporta todas as APIs relacionadas com o Excel na biblioteca javaScript do Office.

Nestas situações, tem de garantir que o seu suplemento nunca está instalado em aplicações do Office ou versões do Office nas quais não pode ser executado.

Também existem cenários em que pretende controlar que funcionalidades do seu suplemento estão visíveis para os utilizadores com base na respetiva aplicação do Office e na versão do Office. Dois exemplos são:

  • O seu suplemento tem funcionalidades úteis no Word e no PowerPoint, como manipulação de texto, mas tem algumas funcionalidades adicionais que só fazem sentido no PowerPoint, como funcionalidades de gestão de diapositivos. Tem de ocultar as funcionalidades apenas do PowerPoint quando o suplemento estiver em execução no Word.
  • O seu suplemento tem uma funcionalidade que requer um método de API JavaScript do Office suportado em algumas versões de uma aplicação do Office, como o Excel de subscrição do Microsoft 365, mas que não é suportado noutras, como o Excel 2016 perpétuo com licenciamento em volume. No entanto, o seu suplemento tem outras funcionalidades que requerem apenas métodos da API JavaScript do Office suportados no Excel 2016 perpétuo com licenciamento em volume. Neste cenário, precisa que o suplemento seja instalável nessa versão do Excel 2016, mas a funcionalidade que requer o método não suportado deve ser ocultada desses utilizadores.

Este artigo ajuda você a entender quais opções você deve escolher para garantir que seu suplemento funcione conforme o esperado e atinja o público mais amplo possível.

Observação

Para obter uma vista de alto nível de onde os Suplementos do Office são atualmente suportados, consulte a página Disponibilidade da plataforma e da aplicação cliente do Office para Suplementos do Office .

Dica

Muitas das tarefas descritas neste artigo são feitas por si, na totalidade ou em parte, quando cria o seu projeto de suplemento com uma ferramenta, como o gerador Yeoman para Suplementos do Office ou um dos modelos de Suplemento do Office no Visual Studio. Nesses casos, interprete a tarefa como o que significa que deve verificar se foi feita.

Utilizar a biblioteca de API JavaScript mais recente do Office

O seu suplemento deve carregar a versão mais atual da biblioteca de API javaScript do Office a partir da rede de entrega de conteúdos (CDN). Para tal, certifique-se de que tem a seguinte script etiqueta no primeiro ficheiro HTML que o suplemento abre. O uso de /1/ na URL da CDN garante a referência à versão mais recente do Office.js.

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

Especificar as aplicações do Office que podem alojar o seu suplemento

Por predefinição, um suplemento é instalável em todas as aplicações do Office suportadas pelo tipo de suplemento especificado (ou seja, Correio, Painel de tarefas ou Conteúdo). Por exemplo, um suplemento do painel de tarefas é instalável por predefinição no Access, Excel, OneNote, PowerPoint, Project e Word.

Para garantir que o seu suplemento é instalável num subconjunto de aplicações do Office, utilize os elementos Anfitriões e Anfitriões no manifesto.

Por exemplo, a seguinte <declaração Anfitriões> e <Anfitriões> especifica que o suplemento pode ser instalado em qualquer versão do Excel, que inclui o Excel na Web, Windows e iPad, mas não pode ser instalado em nenhuma outra aplicação do Office.

<Hosts>
  <Host Name="Workbook" />
</Hosts>

O <elemento Anfitriões> pode conter um ou mais <elementos do Anfitrião> . Deve existir um elemento anfitrião> separado< para cada aplicação do Office na qual o suplemento deve ser instalável. O Name atributo é obrigatório e pode ser definido para um dos seguintes valores.

Nome Aplicativos cliente do Office Tipos de suplemento disponíveis
Documento Word na Web, Windows, Mac, iPad Painel de tarefas
Mailbox Outlook na Web, Windows (novo e clássico), Mac, Android, iOS Email
Notebook OneNote Online Painel de tarefas, Conteúdo
Apresentação PowerPoint na Web, Windows, Mac, iPad Painel de tarefas, Conteúdo
Project Project no Windows Painel de tarefas
Pasta de Trabalho Excel na Web, Windows, Mac, iPad Painel de tarefas, Conteúdo
Banco de dados Acesso (obsoleto) Painel de tarefas

Observação

As aplicações do Office são suportadas em diferentes plataformas e executadas em ambientes de trabalho, browsers, tablets e dispositivos móveis. Normalmente, não pode especificar que plataforma pode ser utilizada para executar o seu suplemento. Por exemplo, se especificar Workbook, tanto o Excel na Web como no Windows podem ser utilizados para executar o seu suplemento. No entanto, se especificar Mailbox, o suplemento não será executado em clientes móveis do Outlook, a menos que defina o ponto de extensão móvel.

Observação

Não é possível aplicar um manifesto de suplemento a mais do que um tipo: Correio, Painel de tarefas ou Conteúdo. Isto significa que, se pretender que o seu suplemento seja instalável no Outlook e numa das outras aplicações do Office, tem de criar dois suplementos, um com um manifesto de Tipo de correio e o outro com um painel de Tarefas ou manifesto de Tipo de conteúdo.

Especifique as versões e plataformas do Office que podem alojar o seu suplemento

Não pode especificar explicitamente as versões e compilações do Office ou as plataformas nas quais o seu suplemento deve ser instalado e não gostaria de o fazer porque teria de rever o seu manifesto sempre que o suporte para as funcionalidades de suplemento que o seu suplemento utiliza fosse expandido para uma nova versão ou plataforma. Em vez disso, especifique no manifesto as APIs de que o suplemento precisa. O Office impede que o suplemento seja instalado em combinações de versões e plataformas do Office que não suportam as APIs e garante que o suplemento não será apresentado em Os Meus Suplementos.

Importante

Utilize apenas o manifesto base para especificar os membros da API que o seu suplemento tem de ter de qualquer valor significativo. Se o seu suplemento utilizar uma API para algumas funcionalidades, mas tiver outras funcionalidades úteis que não requerem a API, deve estruturar o suplemento para que seja instalável nas combinações de plataformas e versões do Office que não suportam a API, mas que proporciona uma experiência reduzida nessas combinações. Para obter mais informações, consulte Estruturar para experiências alternativas.

Conjuntos de requisitos

Para simplificar o processo de especificação das APIs de que o seu suplemento precisa, o Office agrupa a maioria das APIs em conjunto nos conjuntos de requisitos. As APIs no Common API Object Model são agrupadas pela funcionalidade de desenvolvimento que suportam. Por exemplo, todas as APIs ligadas a enlaces de tabela estão no conjunto de requisitos denominado "TableBindings 1.1". As APIs nos modelos de objetos específicos da Aplicação são agrupadas por quando foram lançadas para utilização em suplementos de produção.

Os conjuntos de requisitos têm um controlo de versão. Por exemplo, as APIs que suportam Caixas de Diálogo estão no conjunto de requisitos DiálogoApi 1.1. Quando foram lançadas APIs adicionais que permitem mensagens de um painel de tarefas para uma caixa de diálogo, foram agrupadas na DialogApi 1.2, juntamente com todas as APIs na DialogApi 1.1. Cada versão de um conjunto de requisitos é um superconjunto de todas as versões anteriores.

O suporte do conjunto de requisitos varia consoante a aplicação do Office, a versão da aplicação do Office e a plataforma na qual está a ser executada. Por exemplo, a DialogApi 1.2 não é suportada em versões perpétuas licenciadas em volume do Office antes do Office 2021, mas a DialogApi 1.1 é suportada em todas as versões perpétuas do Office 2016. Pretende que o seu suplemento seja instalável em todas as combinações de plataformas e versões do Office que suportem as APIs que utiliza, pelo que deve especificar sempre no manifesto a versão mínima de cada conjunto de requisitos que o seu suplemento requer. Os detalhes sobre como fazê-lo encontram-se mais adiante neste artigo.

Dica

Para obter mais informações sobre o controlo de versões do conjunto de requisitos, consulte Disponibilidade dos conjuntos de requisitos do Office e, para obter as listas completas de conjuntos de requisitos e informações sobre as APIs em cada uma, comece com os conjuntos de requisitos do Suplemento do Office. Os tópicos de referência para a maioria das APIs Office.js também especificam o conjunto de requisitos a que pertencem (se aplicável).

Observação

Alguns conjuntos de requisitos também têm elementos de manifesto associados aos mesmos. Veja Especificar requisitos num elemento VersionOverrides para obter informações sobre quando este facto é relevante para a estrutura do suplemento.

AS APIs não estão num conjunto de requisitos

Todas as APIs nos modelos específicos da aplicação estão em conjuntos de requisitos, mas algumas delas no modelo de API Comum não estão. Também existe uma forma de especificar uma destas APIs sem conjunto no manifesto quando o suplemento requer uma. Os detalhes estão incluídos mais adiante neste artigo.

Elemento Requirements

Utilize o elemento Requisitos e os respetivos elementos subordinados Conjuntos e Métodos para especificar os conjuntos de requisitos mínimos ou os membros da API que têm de ser suportados pela aplicação do Office para instalar o seu suplemento.

Se a aplicação ou plataforma do Office não suportar os conjuntos de requisitos ou os membros da API especificados no< elemento Requisitos>, o suplemento não será executado nessa aplicação ou plataforma e não será apresentado em Os Meus Suplementos.

Observação

O <elemento Requisitos> é opcional para todos os suplementos, exceto para suplementos do Outlook. Quando o xsi:type atributo do elemento raiz OfficeApp é MailApp, tem de existir um <elemento Requisitos que especifique> a versão mínima do conjunto de requisitos da Caixa de Correio que o suplemento necessita. Para obter mais informações, veja Conjuntos de requisitos da API JavaScript do Outlook.

O seguinte exemplo de código mostra como configurar um suplemento que é instalável em todas as aplicações do Office que suportam o seguinte:

  • TableBindings conjunto de requisitos, que tem uma versão mínima de "1.1".
  • OOXML conjunto de requisitos, que tem uma versão mínima de "1.1".
  • Document.getSelectedDataAsync método.
<OfficeApp ... >
  ...
  <Requirements>
     <Sets DefaultMinVersion="1.1">
        <Set Name="TableBindings" MinVersion="1.1"/>
        <Set Name="OOXML" MinVersion="1.1"/>
     </Sets>
     <Methods>
        <Method Name="Document.getSelectedDataAsync"/>
     </Methods>
  </Requirements>
    ...
</OfficeApp>

Tenha em atenção o seguinte sobre este exemplo.

  • O <elemento Requisitos> contém os <elementos subordinados Conjuntos> e <Métodos> .
  • O <elemento Sets> pode conter um ou mais <elementos Definir> . DefaultMinVersionespecifica o valor predefinido MinVersion de todos os elementos de Conjunto> subordinados<.
  • Um elemento Set especifica um conjunto de requisitos que a aplicação do Office tem de suportar para tornar o suplemento instalável. O Name atributo especifica o nome do conjunto de requisitos. Especifica MinVersion a versão mínima do conjunto de requisitos. MinVersionsubstitui o valor do DefaultMinVersion atributo nos Conjuntos principais<>.
  • O <elemento Métodos> pode conter um ou mais elementos do Método . Não pode utilizar o <elemento Métodos> com suplementos do Outlook.
  • O <elemento Método> especifica um método individual que a aplicação do Office tem de suportar para tornar o suplemento instalável. O Name atributo é necessário e especifica o nome do método qualificado com o respetivo objeto principal.

Estruturar para experiências alternativas

As funcionalidades de extensibilidade fornecidas pela plataforma de Suplementos do Office podem ser divididas de forma útil em três tipos:

  • Funcionalidades de extensibilidade que estão disponíveis imediatamente após a instalação do suplemento. Pode utilizar este tipo de funcionalidade ao configurar um elemento VersionOverrides no manifesto. Um exemplo deste tipo de funcionalidade é Comandos de Suplemento, que são botões e menus personalizados do friso.
  • Funcionalidades de extensibilidade que só estão disponíveis quando o suplemento está em execução e que são implementadas com Office.js APIs JavaScript; por exemplo, Caixas de Diálogo.
  • Funcionalidades de extensibilidade que só estão disponíveis no runtime, mas que são implementadas com uma combinação de Office.js JavaScript e configuração num <elemento VersionOverrides> . Alguns exemplos são funções personalizadas do Excel, início de sessão único e separadores contextuais personalizados.

Se o seu suplemento utilizar uma funcionalidade de extensibilidade específica para algumas das suas funcionalidades, mas tiver outras funcionalidades úteis que não exijam a funcionalidade de extensibilidade, deve estruturar o suplemento para que seja instalável nas combinações de plataformas e versões do Office que não suportam a funcionalidade de extensibilidade. Pode proporcionar uma experiência valiosa, embora diminuída, nessas combinações.

Pode implementar este design de forma diferente consoante a forma como a funcionalidade de extensibilidade é implementada:

Verificações de tempo de execução do método e do suporte do conjunto de requisitos

Teste no runtime para descobrir se o Office do utilizador suporta um conjunto de requisitos com o método isSetSupported . Transmita o nome do conjunto de requisitos e a versão mínima como parâmetros. Se o conjunto de requisitos for suportado, isSetSupported devolve true. O código a seguir mostra um exemplo.

if (Office.context.requirements.isSetSupported('WordApi', '1.2'))
{
   // Code that uses API members from the WordApi 1.2 requirement set.
} else {
   // Provide diminished experience here. E.g., run alternate code when the user's Word is volume-licensed perpetual Word 2016 (which doesn't support WordApi 1.2).
}

Sobre este código, observe:

  • É necessário o primeiro parâmetro. É uma cadeia que representa o nome do conjunto de requisitos. Para saber mais sobre os conjuntos de requisitos disponíveis, confira Conjuntos de requisitos de Suplemento do Office.
  • O segundo parâmetro é opcional. É uma cadeia que especifica a versão do conjunto de requisitos mínimo que a aplicação do Office tem de suportar para que o código na if instrução seja executado (por exemplo, "1,9"). Se não for utilizada, é assumida a versão "1.1".

Aviso

Ao chamar o isSetSupported método , o valor do segundo parâmetro (se especificado) deve ser uma cadeia e não um número. O analisador JavaScript não pode diferenciar entre valores numéricos, como 1,1 e 1,10, enquanto pode para valores de cadeia, como "1,1" e "1,10".

A tabela seguinte mostra os nomes dos conjuntos de requisitos para os modelos de API específicos da aplicação.

Aplicativo do Office RequirementSetName
Excel ExcelApi
OneNote OneNoteApi
Outlook Caixa de correio
PowerPoint PowerPointApi
Word WordApi

Segue-se um exemplo de utilização do método com um dos conjuntos de requisitos do modelo de API Comum.

if (Office.context.requirements.isSetSupported('CustomXmlParts'))
{
    // Run code that uses API members from the CustomXmlParts requirement set.
}
else
{
    // Run alternate code when the user's Office application doesn't support the CustomXmlParts requirement set.
}

Observação

O isSetSupported método e os conjuntos de requisitos para estas aplicações estão disponíveis no ficheiro de Office.js mais recente na CDN. Se não utilizar Office.js da CDN, o suplemento poderá gerar exceções se estiver a utilizar uma versão antiga da biblioteca na qual isSetSupported não está definido. Para obter mais informações, consulte Utilizar a biblioteca de API JavaScript mais recente do Office.

Quando o seu suplemento depende de um método que não faz parte de um conjunto de requisitos, utilize a verificação de runtime para determinar se o método é suportado pela aplicação do Office, conforme mostrado no exemplo de código seguinte. Para obter uma lista completa dos métodos que não pertencem a um conjunto de requisitos, confira Conjuntos de requisitos de Suplemento do Office.

Observação

Recomendamos limitar o uso desse tipo de verificação no tempo de execução no código de seu suplemento.

O seguinte exemplo de código verifica se a aplicação do Office suporta document.setSelectedDataAsync.

if (Office.context.document.setSelectedDataAsync)
{
    // Run code that uses `document.setSelectedDataAsync`.
}

Especificar requisitos num elemento VersionOverrides

O elemento VersionOverrides foi adicionado ao esquema de manifesto principalmente, mas não exclusivamente, para suportar funcionalidades que têm de estar disponíveis imediatamente após a instalação de um suplemento, como comandos de suplementos (botões e menus personalizados do friso). O Office tem de conhecer estas funcionalidades quando analisar o manifesto do suplemento.

Suponha que o seu suplemento utiliza uma destas funcionalidades, mas o suplemento é valioso e deve ser instalável, mesmo em versões do Office que não suportam a funcionalidade. Neste cenário, identifique a funcionalidade com um elemento Requisitos (e os respetivoselementos subordinados Conjuntos e Métodos ) que inclui como subordinado do <próprio elemento VersionOverrides> em vez de como subordinado do elemento base OfficeApp . O efeito desta ação é que o Office permitirá a instalação do suplemento, mas o Office irá ignorar alguns dos elementos subordinados do <elemento VersionOverrides> nas versões do Office em que a funcionalidade não é suportada.

Especificamente, os elementos subordinados das <VersionOverrides> que substituem os elementos no manifesto base, como um <elemento Anfitriões> , são ignorados e os elementos correspondentes do manifesto base são utilizados. No entanto, podem existir elementos subordinados em <VersionOverrides que implementam funcionalidades> adicionais em vez de substituir definições no manifesto base. Dois exemplos são o WebApplicationInfo e EquivalentAddins. Estas partes das <VersionOverrides não serão ignoradas>, partindo do princípio de que a plataforma e a versão do Office suportam a funcionalidade correspondente.

Para obter informações sobre os elementos descendentes do< elemento Requisitos>, veja o elemento Requisitos anteriormente neste artigo.

Apresentamos um exemplo a seguir.

<VersionOverrides ... >
   ...
   <Requirements>
      <Sets DefaultMinVersion="1.1">
         <Set Name="WordApi" MinVersion="1.2"/>
      </Sets>
   </Requirements>
   <Hosts>

      <!-- ALL MARKUP INSIDE THE HOSTS ELEMENT IS IGNORED WHEREVER WordApi 1.2 IS NOT SUPPORTED -->

      <Host xsi:type="Workbook">
         <!-- markup for custom add-in commands -->
      </Host>
   </Hosts>
</VersionOverrides>

Aviso

Tenha muito cuidado antes de incluir um <elemento Requisitos> numa <VersionOverrides>, uma vez que nas combinações de plataformas e versões que não suportam o requisito, nenhum dos comandos de suplemento será instalado, mesmo aqueles que invocam funcionalidades que não precisam do requisito. Considere, por exemplo, um suplemento com dois botões de friso personalizados. Uma delas chama as APIs JavaScript do Office que estão disponíveis no conjunto de requisitos ExcelApi 1.4 (e posterior). As outras chamadas são APIs que só estão disponíveis no ExcelApi 1.9 (e posterior). Se colocar um requisito para o <ExcelApi 1.9 nas VersionOverrides, quando a versão 1.9 não for suportada, nenhum dos botões aparecerá no friso>. Uma estratégia melhor neste cenário seria utilizar a técnica descrita em Verificações de runtime para o método e suporte do conjunto de requisitos. O código invocado pelo segundo botão utiliza isSetSupported primeiro para verificar o suporte do ExcelApi 1.9. Se não for suportado, o código dá ao utilizador uma mensagem a indicar que esta funcionalidade do suplemento não está disponível na respetiva versão do Office.

Dica

Não vale a pena repetir um elemento Requisito num <VersionOverrides> que já aparece no manifesto base. Se o requisito for especificado no manifesto base, o suplemento não pode ser instalado quando o requisito não é suportado, pelo que o Office nem sequer analisa o <elemento VersionOverrides> .

Confira também