Especificar requisitos da API e de aplicativos do Office

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.

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/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.

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.

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.

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.

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:

• Para obter as funcionalidades implementadas inteiramente com JavaScript, veja Verificações de runtime para o método e o suporte do conjunto de requisitos.
• Para obter funcionalidades que exijam a configuração de um <elemento VersionOverrides> , veja Especificar requisitos num elemento VersionOverrides.

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".

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

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.
}

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.

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>

Confira também

• Manifesto de Suplementos do Office
• Conjuntos de requisitos de Suplemento do Office
• Word-Add-in-Get-Set-EditOpen-XML