Especificar aplicativos do Office e requisitos de API com o manifesto unificado

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:

• Executar em um único aplicativo do Office (por exemplo, Word ou Excel) ou diversos 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.
• Ser projetado para uso somente em um formato móvel.

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. Três 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 da API JavaScript do Office que tem suporte em 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.
• Seu suplemento tem recursos que são suportados no Office para área de trabalho, mas não no Office móvel.

Este artigo ajuda você a entender como 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

Para especificar os aplicativos do Office nos quais o suplemento pode ser instalado, use a "extensions.requirements.scopes" matriz. Especifique qualquer subconjunto de "mail", "workbook", "document", e "presentation". A tabela a seguir mostra quais combinações de aplicativo e plataforma do Office correspondem a esses valores. Ele também mostra que tipo de suplemento pode ser instalado para cada escopo.

Por exemplo, o JSON a seguir 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.

"extensions": [
    {
        "requirements": {
            "scopes": [ "workbook" ],
        },
        ...
    }
]

Especificar quais APIs do Office seu suplemento precisa

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.

Propriedade extensions.requirements.capabilities

Use a "requirements.capabilities" propriedade para especificar os conjuntos de requisitos mínimos que devem ser compatíveis com o aplicativo do Office para instalar seu suplemento. Se o aplicativo ou a plataforma do Office não for compatível com os conjuntos de requisitos ou os membros da API especificados na "requirements.capabilities" propriedade, 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 todas as combinações de aplicativo e plataforma do Office que dão suporte ao 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".

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

Especificar os fatores forma nos quais o suplemento pode ser instalado

Para um suplemento do Outlook, você pode especificar se o suplemento deve ser instalável no desktop (inclui tablets) ou em fatores forma móveis. Para configurar isso, use a "extensions.requirements.formFactors" propriedade. O exemplo a seguir mostra como tornar o suplemento instalável apenas em dispositivos desktop.

"extensions": [
    {
        "requirements": {
            ...
            "formFactors": [
                "desktop"
            ]
        },
        ...
    }
]

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. 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 de manifesto. 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 o manifesto, consulte a seção "Recursos de filtro" de Como usar a propriedade "requisitos" no manifesto unificado do Microsoft 365.

Confira também

• Manifesto dos suplementos do Office
• Conjuntos de requisitos de Suplemento do Office
• Como usar a propriedade "requirements" no manifesto unificado para o Microsoft 365