Partilhar via

Especifique as aplicações do Office e os requisitos de API com o manifesto unificado

  • Artigo

Observação

Para obter informações sobre como especificar requisitos com o manifesto apenas de suplemento, consulte Especificar anfitriões do Office e requisitos de API com o manifesto apenas de suplemento.

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 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.
  • 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.
  • Ser concebido para utilização apenas num fator de forma móvel.

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. Três exemplos são:

  • O seu suplemento tem funcionalidades úteis tanto no Word como no PowerPoint, como a 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 Excel 2016 perpétuas licenciadas em volume. No entanto, o seu suplemento tem outras funcionalidades que requerem apenas métodos da API JavaScript do Office que são suportados em Excel 2016 perpétuas licenciadas 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.
  • O seu suplemento tem funcionalidades suportadas no Office para ambiente de trabalho, mas não no Office para dispositivos móveis.

Este artigo ajuda-o a compreender como garantir que o seu suplemento funciona conforme esperado e atinge 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/hosted/office.js" type="text/javascript"></script>

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

Para especificar as aplicações do Office nas quais o seu suplemento pode ser instalado, utilize a matriz "extensions.requirements.scopes". Especifique qualquer subconjunto de "correio", "livro", "documento" e "apresentação". A tabela seguinte mostra que combinações de aplicações e plataformas do Office correspondem a estes valores. Também mostra que tipo de suplemento pode ser instalado para cada âmbito.

Nome Aplicativos cliente do Office Tipos de suplemento disponíveis
document Word na Web, Windows, Mac, iPad Painel de tarefas
Email Outlook na Web, Windows (novo e clássico), Android, iOS Email
apresentação PowerPoint na Web, Windows, Mac, iPad Painel de tarefas, Conteúdo
pasta de trabalho Excel na Web, Windows, Mac, iPad Painel de tarefas, Conteúdo

Observação

Os suplementos de conteúdo têm uma propriedade "extensions.contentRuntimes". Não podem ter uma propriedade "extensions.runtimes", pelo que não podem ser combinadas com um painel de Tarefas ou um suplemento Correio. Para obter mais informações sobre suplementos de Conteúdo, consulte Content Office Add-ins (Suplementos do Office de Conteúdo).

Por exemplo, o seguinte JSON especifica que o suplemento pode ser instalado em qualquer versão do Excel, que inclui Excel na Web, Windows e iPad, mas não pode ser instalado em nenhuma outra aplicação do Office.

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

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 "livro", tanto Excel na Web como no Windows podem ser utilizados para executar o seu suplemento. No entanto, se especificar "correio", o suplemento não será executado em clientes móveis do Outlook, a menos que defina o ponto de extensão móvel.

Especifique as APIs do Office que o seu suplemento precisa

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 a propriedade "requisitos" que é um subordinado direto de "extensões" 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 esta finalidade, utilize propriedades "requisitos" que não sejam subordinados diretos de "extensõ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 de 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).

propriedade extensions.requirements.capabilities

Utilize a propriedade "requirements.capabilities" para especificar os conjuntos de requisitos mínimos 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 na propriedade "requirements.capabilities", o suplemento não será executado nessa aplicação ou plataforma e não será apresentado em Os Meus Suplementos.

Dica

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. Se o suplemento necessitar de uma API que não esteja num conjunto de requisitos, pode implementar um marcar de runtime para a disponibilidade da API e apresentar uma mensagem aos utilizadores do suplemento, caso não seja suportada. Para obter mais informações, veja Verificar a disponibilidade da API no runtime.

O seguinte exemplo de código mostra como configurar um suplemento que é instalável em todas as combinações de aplicações e plataformas 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".
"extensions": [
    {
        "requirements": {
            "capabilities": [ 
                {
                    "name": "TableBindings",
                    "minVersion": "1.1"
                },
                {
                    "name": "OOXML",
                    "minVersion": "1.1"
                }
            ],
        },
        ...
    }
]

Dica

Para obter mais informações e outro exemplo de utilização da propriedade "extensions.requirements", consulte a secção "extensions.requirements" em Especificar requisitos de Suplementos do Office no manifesto unificado do Microsoft 365.

Especifique os fatores de formulário nos quais o suplemento pode ser instalado

Para um suplemento do Outlook, pode especificar se o suplemento deve ser instalável no ambiente de trabalho (inclui tablets) ou fatores de forma móvel. Para configurar esta opção, utilize a propriedade "extensions.requirements.formFactors". O exemplo seguinte mostra como tornar o suplemento do Outlook instalável em ambos os fatores de forma.

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

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. 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 de manifesto. 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:

Confira também