Entender a lógica da configuração de requisitos da API

Você pode limitar em quais aplicativos cliente do Office e versões seu suplemento pode ser instalado. Você também pode impedir que alguns recursos do suplemento fiquem disponíveis em determinados aplicativos e versões cliente. Você faz isso especificando no manifesto certos requisitos que devem ser atendidos por um cliente do Office antes que ele possa instalar o suplemento e antes que determinados recursos estejam disponíveis.

Há três maneiras de limitar o suplemento/recurso, discutidas nas seções a seguir. Mas confira também Limitar por plataforma em tempo de execução.

Limitar por aplicativo do Office

Para limitar o suplemento/recurso a um subconjunto adequado do Excel, Outlook, PowerPoint ou Word, use a "requirements.scopes" propriedade. (Os suplementos do OneNote e do Project não podem usar o manifesto unificado. Para trabalhar com eles, consulte a seção Aplicar esta orientação ao manifesto somente do suplemento.) Por exemplo, o JSON a seguir limita o suplemento ao Outlook e ao Excel.

"requirements": {
    "scopes": [ "mail", "workbook" ]
    --- Possibly other child properties of requirements here.
}

Lembre-se dos seguintes pontos sobre como o Office interpreta a "scopes" matriz.

• Inclua na matriz os aplicativos nos quais você deseja que o suplemento/recurso esteja disponível. Para bloquear a disponibilidade em um aplicativo, deixe-o fora da matriz.
• Se você quiser o suplemento/recurso disponível em todos os aplicativos, não inclua uma "scopes" propriedade. Ele só deve ser usado quando você deseja limitar o suplemento/recurso a um subconjunto apropriado dos aplicativos. Incluir todos os quatro valores possíveis é funcionalmente equivalente a não ter nenhuma "scopes" propriedade.
• Pode ser útil pensar na matriz como um conjunto de condições "OU". Seu manifesto está dizendo ao cliente do Office do usuário: "Permitir este suplemento/recurso se você for o Outlook ou o Excel".

Limite por fator forma

Você pode limitar os suplementos do Outlook por fator forma. Para limitar o suplemento/recurso a dispositivos desktop (incluindo tablets) ou dispositivos móveis, use a "requirements.formFactors" propriedade.

Por exemplo, o JSON a seguir limita o suplemento a dispositivos da área de trabalho.

"requirements": {
    "formFactors": [ "desktop" ]
    --- Possibly other child properties of requirements here.
}

Se o "formFactors" elemento não estiver presente, o suplemento/recurso estará disponível em ambos os tipos de fatores forma. Incluir todos os valores possíveis é funcionalmente equivalente a não ter nenhuma "formFactors" propriedade. Portanto, use a propriedade somente quando quiser disponibilizá-la apenas em apenas um formato.

Limite por suporte de conjunto de requisitos

Para limitar o suplemento/recurso a clientes do Office que dão suporte a determinados conjuntos de requisitos, use a "requirements.capabilities" propriedade. Por exemplo, o JSON a seguir limita o suplemento/recurso às versões do Office que dão suporte aos conjuntos de requisitos Mailbox 1.10 ou posterior eDialogApi 1.2 ou posterior.

"requirements": {
    "capabilities": [
        {
            "name": "Mailbox",
            "minVersion": "1.10"
        },
        {
            "name": "DialogAPI",
            "minVersion": "1.2"
        }
    ]
    --- Possibly other child properties of requirements here.
}

Lembre-se dos seguintes pontos sobre como o Office interpreta a "capabilities" matriz.

• Se você quiser o suplemento/recurso disponível em qualquer cliente do Office (exceto aqueles bloqueados por um requisito de escopo ou fator forma), independentemente de quais APIs Office.js ele dá suporte, não inclua uma "capabilities" propriedade. Ele só deve ser usado quando você deseja limitar o suplemento/recurso a clientes que dão suporte a determinados conjuntos de requisitos.

• O cliente do Office deve dar suporte a todos os conjuntos de requisitos da matriz para que o suplemento/recurso esteja disponível.

• Pode ser útil pensar na matriz como um conjunto de condições "AND". Seu manifesto está dizendo ao cliente do Office do usuário: "Permita este suplemento/recurso somente se você der suporte à Caixa de Correio 1.10eà DialogApi 1.2".

• Se não houver nenhum "maxVersion" filho do objeto de funcionalidade, o Office interpretará o "minVersion" como significando "esta versão ou posterior".

• Se houver um "maxVersion", mas não "minVersion", então o Office interpreta o "maxVersion" como significando "esta versão ou anterior". Para todos os conjuntos de requisitos, "1.1" é a versão mais antiga.

• Se a "maxVersion" e "minVersion" estiverem presentes, o Office interpretará as duas propriedades como uma unidade que significa "apenas versões neste intervalo (inclusivo)". Por exemplo, o JSON a seguir limita o suplemento/recurso às versões do Office que dão suporte às versões 1.6 a 1.16 do conjunto de requisitos ExcelApi .

  "requirements": {
      "capabilities": [
          {
              "name": "ExcelApi",
              "minVersion": "1.6",
              "maxVersion": "1.16"
          }
      ]
  }
  

Combinar tipos de limitações

Um "requirements" objeto pode incluir dois ou todos os três tipos de propriedades filho. Quando isso acontece, o suplemento/recurso do Office é limitado a clientes do Office que atendem a todos os requisitos especificados. Por exemplo, o JSON a seguir garante que o suplemento/recurso esteja disponível somente no Outlook, somente em versões compatíveis com Caixa de Correio 1.12 ou posterior e somente em fatores forma de área de trabalho.

"requirements": {
    "scopes": [ "mail" ],
    "capabilities": [
        {
            "name": "Mailbox",
            "minVersion": "1.12"
        }
    ],
    "formFactors": [ "desktop" ]
}

Limitar a instalação de suplementos que dão suporte a vários aplicativos do Office

A lógica da matriz pode dificultar o "capabilities" uso das limitações do conjunto de requisitos em suplementos que dão suporte a "scopes" vários aplicativos do Office, ou seja, quando há mais de um valor na matriz (ou não há nenhuma "scopes" propriedade). Considere o cenário a seguir no qual é necessário haver limites para onde o suplemento pode ser instalado, mas não há limitações para recursos específicos no suplemento.

O suplemento deve ser instalado no Outlook e no Excel, mas não deve ser instalado em outros aplicativos do Office. Então, há um "requirements" filho que "extensions" tem uma "scopes" propriedade como a seguinte.

"extensions": [
    {
        "requirements": {
            "scopes": [ "mail", "workbook" ]
        }
    }
    --- Other child properties of extensions here.
]

Mas a funcionalidade do suplemento no Outlook usa APIs no conjunto de requisitos da Caixa de Correio 1.11 , enquanto sua funcionalidade no Excel usa APIs no conjunto de requisitos ExcelApi 1.10 . É natural pensar que um "capabilities" objeto deve ser adicionado ao objeto de requisito como o JSON a seguir.

"extensions": [
    {
        "requirements": {
            "scopes": [ "mail", "workbook" ],
            "capabilities": [ 
                {
                    "name": "Mailbox",
                    "minVersion": "1.11"
                },
                {
                    "name": "ExcelApi",
                    "minVersion": "1.10"
                }
            ],
        }
    }
    --- Other child properties of extensions here.
]

Mas essa configuração garante que o suplemento/recurso não estará disponível em nenhuma versão do Office porque a Caixa de Correio tem suporte apenas no Outlook e a ExcelApi tem suporte apenas no Excel. Portanto, não há aplicativo do Office que dê suporte a ambos.

Para atingir os dois objetivos de tornar o suplemento instalável no (1) Outlook, mas disponível apenas em versões do Outlook que oferecem suporte à Caixa de Correio 1.11 e (2) no Excel, mas disponível apenas em versões do Excel que oferecem suporte ao ExcelApi 1.10, os objetos de "recursos" devem ser movidos para "extensions.requirements" fora do objeto para um ou mais objetos filho "extensions.{FEATURE}.requirements" , em que {FEATURE} é um filho de "extensions", como "runtimes" ou "ribbons".

Para obter um exemplo concreto, vamos estender o cenário para especificar que o suplemento implementa comandos de função seguindo as diretrizes em Criar comandos de suplemento com o manifesto unificado para Microsoft 365. Especificamente, o suplemento tem as seguintes características.

• O suplemento tem botões de faixa de opções personalizados no Outlook e no Excel que disparam um comando de função em um arquivo commands.js .
• Para dar suporte ao comando function, o manifesto tem uma "extensions.runtimes.actions.actionId" propriedade cujo valor é "doSomething".
• O Office.onReady método no arquivo commands.js testa o Office.context.host e as ramificações, dependendo se é Outlook ou Excel. Se for o Outlook, ele chama Office.Action.associate para vincular "doSomething" a uma função chamada doSomethingInOutlook. Se o host for Excel, ele chamará associate para vincular "doSomething" a uma função chamada doSomethingInExcel.
• Para implementar os botões da faixa de opções, o manifesto inicialmente tem um único objeto da faixa de opções em uma matriz "faixas de opções ". E esse objeto da faixa de opções tem um controle com uma propriedade "actionId" definida como "doSomething".

É essa última característica que precisa ser alterada para atingir os dois objetivos. A seguir está a estratégia.

1. Remova toda "capabilities" a matriz do objeto, para "extensions.requirements" que ela volte a parecer como no primeiro bloco de código desta seção.
2. Copie o objeto da faixa de opções, de modo que agora haja dois objetos da "ribbons" faixa de opções na matriz.
3. No primeiro objeto da faixa de opções, adicione um objeto de funcionalidade que especifique o conjunto de requisitos da Caixa de Correio 1.11 .
4. No segundo objeto da faixa de opções, adicione um objeto de funcionalidade que especifique o conjunto de requisitos ExcelApi 1.10 .

A "ribbons"matriz agora deve ser semelhante à seguinte.

"ribbons": [
    {
        "requirements": {
            "capabilities": [
                {
                    "name": "Mailbox",
                    "minVersion": "1.11"
                }
            ]
        },
            
        --- Other children of the Outlook ribbon object here.
        --- These might be identical to the Excel ribbon object below.
    },
    {
        "requirements": {
            "capabilities": [
                {
                    "name": "ExcelApi",
                    "minVersion": "1.10"
                }
            ]
        },                

            
        --- Other children of the Excel ribbon object here.
        --- These might be identical to the Outlook ribbon object above.
    }
],

Essas alterações têm os efeitos desejados:

• O suplemento pode ser instalado no Outlook e no Excel.
• O controle da faixa de opções só estará disponível nas versões do Outlook que oferecem suporte à Caixa de Correio 1.11 e nas versões do Excel que oferecem suporte à ExcelApi 1.10.

Aplicar esta orientação ao manifesto somente do suplemento

A lógica de como o Office processa a configuração de requisitos no manifesto somente do suplemento é quase a mesma que no manifesto unificado, mas há algumas diferenças.

Limitar por aplicativo do Office no manifesto apenas do suplemento

Os suplementos do Outlook e os suplementos do painel de tarefas para todos os suplementos que não são do Outlook têm seus próprios esquemas de manifesto, portanto, um suplemento do Outlook não pode ser combinado com nenhum outro aplicativo do Office no mesmo suplemento. Os suplementos de conteúdo também têm seu próprio esquema de manifesto e têm suporte apenas no Excel e no PowerPoint. O restante desta seção é sobre a limitação por aplicativo nas categorias de painel de tarefas, suplemento e suplemento de conteúdo.

O equivalente da "scopes" propriedade é o elemento Hosts . Assim como pode haver um "requirements.scopes" como um filho direto de "extensions" ou um filho de uma das outras propriedades filho de "extensions", também pode haver um <Hosts> elemento na raiz do manifesto apenas do suplemento ou em um filho <VersionOverrides>.

Não ter nenhum <Hosts> elemento significa que o suplemento/recurso está disponível em todos os aplicativos possíveis do Office, que são Excel e PowerPoint para suplementos de conteúdo e todos os aplicativos, exceto os suplementos do Outlook para painel de tarefas. Portanto, inclua um <Hosts> elemento quando quiser limitar a disponibilidade do suplemento/recurso.

Limite por requisito definido com o manifesto somente do suplemento

O equivalente da "capabilities" propriedade é o elemento Sets . Também pode estar no manifesto básico ou em um filho <VersionOverrides>.

Não ter nenhum <Sets> elemento significa que o suplemento/recurso está disponível em todas as versões de aplicativos do Office, independentemente dos conjuntos de requisitos a que eles dão suporte. Portanto, inclua um <Sets> elemento quando quiser limitar a disponibilidade do suplemento/recurso.

Assim como no manifesto unificado, é possível criar inadvertidamente um manifesto que bloqueia o suplemento/recurso para todos os clientes do Office. (Confira Limitar a instalação de suplementos que dão suporte a vários aplicativos do Office para obter uma descrição do problema). Por exemplo, incluir elementos Set para WordApi 1.4 e ExcelApi 1.10 teria esse efeito. A solução é paralela à solução para o manifesto unificado. Nesse cenário, execute estas etapas.

1. Remova os elementos problemáticos <Set> do manifesto base.
2. Copie o <VersionOverrides> elemento para que agora haja dois deles.
3. No primeiro <VersionOverrides> , tem um <Hosts> elemento que especifica apenas "Documento" e um <Sets><Set> que especifica apenas WordApi 1.4.
4. No segundo <VersionOverrides> , tem um <Hosts> elemento que especifica apenas "Pasta de trabalho" e um <Sets><Set> que especifica apenas ExcelApi 1.10.

Limitar por fator forma com o manifesto somente do suplemento

Quando o manifesto somente do suplemento é usado, o fator forma da área de trabalho sempre tem suporte em todos os suplementos, e o fator forma móvel só é possível para suplementos do Outlook.

Para um suplemento do Outlook, a presença ou ausência de um elemento MobileFormFactor , como filho de um <VersionOverrides><Hosts><Host> elemento, determina se o suplemento está disponível em dispositivos móveis. Consulte Host para obter mais informações.

Limitar por plataforma em tempo de execução

Você não pode limitar um suplemento/recurso por plataforma (Windows, Web, Mac, iOS ou Android) usando as técnicas deste artigo. Não há nenhuma "platform" propriedade no "requirements" objeto no manifesto unificado e nenhum <Platforms> filho do <Requirements> elemento no manifesto apenas do suplemento. Embora haja alguns conjuntos de requisitos que têm suporte apenas em uma plataforma, eles não são permitidos na propriedade ou no "capabilities"<Sets> elemento. Há uma solução alternativa para suplementos implantados por administradores do Microsoft 365 no portal de aplicativos integrados. Projete o suplemento para que ele verifique em runtime a plataforma. Se for uma plataforma à qual você não deseja que o suplemento seja compatível, mostre uma mensagem ao usuário informando que o suplemento não funcionará em sua versão do Office e sugira para qual plataforma o usuário deve mudar. Na verdade, há duas maneiras de fazer uma marcar de tempo de execução.

• Verifique a propriedade Office.context.platform .
• Chame o método Office.context.requirements.isSetSupported e passe o nome de um conjunto de requisitos específico da plataforma.

Para obter orientação, consulte Noções básicas sobre conjuntos de requisitos específicos da plataforma e Verificar a disponibilidade da API em tempo de execução.

Confira também

• Como usar a propriedade "requirements" no manifesto unificado para o Microsoft 365
• Especificar aplicativos do Office e requisitos de API com o manifesto unificado
• Especificar aplicativos do Office e requisitos de API com o manifesto somente do suplemento