Especificar aplicativos do Office e requisitos de API com o manifesto somente do suplemento

Seu Suplemento do Office pode depender de um aplicativo específico do Office (também chamado de host do Office) ou de membros específicos da Biblioteca JavaScript do Office (office.js). Por exemplo, o suplemento pode:

• Execute em um único aplicativo do Office (por exemplo, Word ou Excel) ou em vários aplicativos.
• Use as APIs JavaScript do Office que estão disponíveis apenas em algumas versões do Office. Por exemplo, a versão perpétua licenciada por volume do Excel 2016 não dá suporte a todas as APIs relacionadas ao Excel na biblioteca JavaScript do Office.

Nessas situações, você precisa garantir que o suplemento nunca seja instalado em aplicativos do Office ou versões do Office nas quais ele não possa ser executado.

Também há cenários em que você deseja controlar quais recursos do suplemento são visíveis para os usuários com base em seu aplicativo do Office e versão do Office. Dois exemplos são:

• O suplemento tem recursos que são úteis no Word e no PowerPoint, como manipulação de texto, mas tem alguns recursos adicionais que só fazem sentido no PowerPoint, como recursos de gerenciamento de slides. Você precisa ocultar os recursos somente do PowerPoint quando o suplemento estiver em execução no Word.
• Seu suplemento tem um recurso que requer um método de API JavaScript do Office que é compatível com algumas versões de um aplicativo do Office, como a assinatura do Microsoft 365 Excel, mas não tem suporte em outras, como o Excel 2016 perpétuo licenciado por volume. Mas seu suplemento tem outros recursos que exigem apenas métodos da API JavaScript do Office com suporte no Excel 2016 perpétuo licenciado por volume. Nesse cenário, você precisa que o suplemento seja instalável nessa versão do Excel 2016, mas o recurso que requer o método sem suporte deve ser oculto desses usuários.

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.

Usar a biblioteca mais recente da API JavaScript do Office

Seu suplemento deve carregar a versão mais atual da biblioteca da API JavaScript do Office da CDN (Rede de Distribuição de Conteúdo). Para fazer isso, verifique se você tem a seguinte <script> marca no primeiro arquivo HTML que seu 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 quais aplicativos do Office podem hospedar seu suplemento

Por padrão, um suplemento pode ser instalado em todos os aplicativos do Office compatíveis com o tipo de suplemento especificado (ou seja, Email, Painel de tarefas ou Conteúdo). Por exemplo, um suplemento do painel de tarefas pode ser instalado por padrão no Access, Excel, OneNote, PowerPoint, Project e Word.

Para garantir que seu suplemento seja instalável apenas em um subconjunto de aplicativos do Office, use os hosts e elementos Host no manifesto somente do suplemento.

Por exemplo, a declaração a seguir <Hosts> e <Host> especifica que o suplemento pode ser instalado em qualquer versão do Excel, o que inclui o Excel na Web, Windows e iPad, mas não pode ser instalado em nenhum outro aplicativo do Office.

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

O <Hosts> elemento pode conter um ou mais <Host> elementos. Deve haver um elemento separado <Host> para cada aplicativo do Office no qual o suplemento deve ser instalável. O Name atributo é necessário e pode ser definido como um dos seguintes valores.

Especificar quais versões e plataformas do Office podem hospedar seu suplemento

Você não pode especificar explicitamente as versões e builds do Office ou as plataformas nas quais seu suplemento deve ser instalável, e você não iria querer porque teria que revisar seu manifesto sempre que o suporte para os recursos do suplemento que seu suplemento usa fosse estendido para uma nova versão ou plataforma. Em vez disso, especifique no manifesto as APIs de que seu suplemento precisa. O Office impede que o suplemento seja instalado em combinações de versão e plataforma do Office que não dão suporte às APIs e garante que o suplemento não aparecerá em Meus Suplementos.

Conjuntos de requisitos

Para simplificar o processo de especificação das APIs necessárias para o suplemento, o Office agrupa a maioria das APIs em conjuntos de requisitos. As APIs no Common API Object Model são agrupadas pelo recurso de desenvolvimento a que elas dão suporte. Por exemplo, todas as APIs conectadas a associações de tabela estão no conjunto de requisitos chamado "TableBindings 1.1". As APIs nos modelos de objeto específicos do aplicativo são agrupadas por quando foram liberadas para uso em suplementos de produção.

Os conjuntos de requisitos têm controle de versão. Por exemplo, as APIs que dão suporte a caixas de diálogo estão no conjunto de requisitos DialogApi 1.1. Quando APIs adicionais que permitem mensagens de um painel de tarefas para uma caixa de diálogo foram lançadas, elas foram agrupadas em DialogApi 1.2, juntamente com todas as APIs em DialogApi 1.1. Cada versão de um conjunto de requisitos é um superconjunto de todas as versões anteriores.

O suporte ao conjunto de requisitos varia de acordo com o aplicativo do Office, a versão do aplicativo do Office e a plataforma na qual ele está sendo executado. Por exemplo, o ExcelApi 1.17 não tem suporte em versões perpétuas licenciadas por volume do Office antes do Office 2024, mas o ExcelApi 1.14 tem suporte no Office 2021. Você deseja que seu suplemento seja instalável em todas as combinações de plataforma e versão do Office que dão suporte às APIs que ele usa, portanto, você deve sempre especificar no manifesto a versão mínima de cada conjunto de requisitos que seu suplemento exige. Detalhes sobre como fazer isso são mais adiante neste artigo.

Elemento Requirements

Use o elemento Requirements e seus conjuntos de elementos filho para especificar os conjuntos de requisitos mínimos que devem ser compatíveis com o aplicativo do Office para instalar o suplemento.

Todas as APIs nos modelos específicos do aplicativo estão em conjuntos de requisitos, mas algumas delas no modelo de API comum não. Use os métodos para especificar os membros da API sem conjunto que seu suplemento exige. Você não pode usar o <Methods> elemento com suplementos do Outlook.

Se o aplicativo ou a plataforma do Office não for compatível com os conjuntos de requisitos ou os membros da API especificados no <Requirements> elemento, o suplemento não será executado nesse aplicativo ou plataforma e não será exibido em Meus Suplementos.

O exemplo de código a seguir mostra como configurar um suplemento que pode ser instalado em todos os aplicativos do Office compatíveis com o seguinte:

• TableBindings conjunto de requisitos, que tem uma versão mínima de "1.1".
• OoxmlCoercion conjunto de requisitos, que tem uma versão mínima de "1.1".
• Document.getSelectedDataAsync metodologia.

<OfficeApp ... >
  ...
  <Requirements>
     <Sets DefaultMinVersion="1.1">
        <Set Name="TableBindings" MinVersion="1.1"/>
        <Set Name="OoxmlCoercion" MinVersion="1.1"/>
     </Sets>
     <Methods>
        <Method Name="Document.getSelectedDataAsync"/>
     </Methods>
  </Requirements>
    ...
</OfficeApp>

Observe o seguinte sobre este exemplo.

• O <Requirements> elemento contém os <Sets> elementos filho e <Methods> .
• O <Sets> elemento pode conter um ou mais <Set> elementos. DefaultMinVersion Especifica o valor padrão MinVersion de todos os elementos filho <Set> .
• Um elemento Set especifica um conjunto de requisitos que o aplicativo do Office deve oferecer suporte 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. MinVersion substitui o valor do DefaultMinVersion atributo no pai <Sets>.
• O <Methods> elemento pode conter um ou mais elementos Method . Você não pode usar o <Methods> elemento com suplementos do Outlook.
• O <Method> elemento especifica um método individual que o aplicativo do Office deve dar suporte para tornar o suplemento instalável. O Name atributo é necessário e especifica o nome do método qualificado com seu objeto pai.

Design para experiências alternativas

Os recursos de extensibilidade que a plataforma de Suplemento do Office fornece podem ser utilmente divididos em três tipos:

• Recursos de extensibilidade que estão disponíveis imediatamente após a instalação do suplemento. Você pode usar esse tipo de recurso configurando um elemento VersionOverrides no manifesto. Um exemplo desse tipo de recurso são os Comandos de Suplemento, que são botões e menus personalizados da faixa de opções.
• Recursos de extensibilidade que estão disponíveis somente quando o suplemento está em execução e que são implementados com Office.js APIs JavaScript; por exemplo, caixas de diálogo.
• Recursos de extensibilidade que estão disponíveis apenas em tempo de execução, mas são implementados com uma combinação de Office.js JavaScript e configuração em um <VersionOverrides> elemento. Exemplos disso são funções personalizadas do Excel, logon único e guias contextuais personalizadas.

Se o suplemento usa um recurso de extensibilidade específico para algumas de suas funcionalidades, mas tem outra funcionalidade útil que não requer o recurso de extensibilidade, você deve projetar o suplemento para que ele seja instalável em combinações de plataforma e versão do Office que não dão suporte ao recurso de extensibilidade. Pode fornecer uma experiência valiosa, embora reduzida, nessas combinações.

Você implementa esse design de forma diferente dependendo de como o recurso de extensibilidade é implementado:

• Para recursos implementados inteiramente com JavaScript, consulte Verificar a disponibilidade da API em tempo de execução.
• Para recursos que exigem que você configure um <VersionOverrides> elemento, consulte Especificando requisitos em um elemento VersionOverrides.

Especificar requisitos em um elemento VersionOverrides

O elemento VersionOverrides foi adicionado ao esquema de manifesto principalmente, mas não exclusivamente, para dar suporte a recursos que devem estar disponíveis imediatamente após a instalação de um suplemento, como comandos de suplemento (botões e menus personalizados da faixa de opções). O Office deve conhecer esses recursos ao analisar o manifesto do suplemento.

Suponha que seu suplemento use um desses recursos, mas o suplemento é valioso e deve ser instalável, mesmo em versões do Office que não dão suporte ao recurso. Nesse cenário, identifique o recurso usando um elemento Requirements (e seus elementos Conjuntos e Métodos filho) que você inclui como um filho do <VersionOverrides> próprio elemento em vez de como um filho do elemento base OfficeApp . O efeito de fazer isso é que o Office permitirá que o suplemento seja instalado, mas o Office ignorará alguns dos elementos filho do <VersionOverrides> elemento nas versões do Office em que o recurso não tem suporte.

Especificamente, os elementos filho do <VersionOverrides> que substituem elementos no manifesto base, como um <Hosts> elemento, são ignorados e os elementos correspondentes do manifesto base são usados. No entanto, pode haver elementos filho em um <VersionOverrides> que realmente implementam recursos adicionais em vez de substituir as configurações no manifesto base. Dois exemplos são o e EquivalentAddins.WebApplicationInfo Essas partes não <VersionOverrides>serão ignoradas, supondo que a plataforma e a versão do Office ofereçam suporte ao recurso correspondente.

Para obter informações sobre os <Requirements> elementos descendentes do elemento, consulte Elemento de 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 dos suplementos do Office
• Conjuntos de requisitos de Suplemento do Office
• Word-Add-in-Get-Set-EditOpen-XML