Elemento Requirements

  • Artigo

O significado desse elemento depende se ele é usado no manifesto base, como filho de um <elemento VersionOverrides> ou como filho do elemento Overrides.

Dica

Antes de usar esse elemento, familiarize-se com especificar os requisitos de API e hosts do Office

No manifesto base

Quando usado no manifesto base (ou seja, como filho direto do OfficeApp), o <elemento Requisitos> especifica o conjunto mínimo de requisitos de API JavaScript do Office (conjuntos de requisitos e/ou métodos) que seu Suplemento do Office precisa ser ativado pelo Office. O suplemento não será ativado em nenhuma combinação de versão e plataforma do Office (como Windows, Mac, Web e iOS ou iPad) que não dá suporte aos métodos e conjuntos de requisitos especificados.

Tipo de suplemento: Painel de tarefas, Email

Como filho de um elemento VersionOverrides

Quando usado como filho de VersionOverrides, especifica o conjunto mínimo de requisitos de API JavaScript do Office (conjuntos de requisitos e/ou métodos) que devem ser suportados pela versão e plataforma do Office (como Windows, Mac, Web e iOS ou iPad) para que as configurações no elemento VersionOverrides> que substituam as configurações de manifesto base entrem em< vigor.

Considere um suplemento que especifica o requisito A no manifesto base e especifica o requisito B dentro dos <VersionOverrides>.

  • Se a plataforma e a versão do Office não dão suporte a A, o suplemento não será ativado e o Office não analisará a <seção VersionOverrides> do manifesto.
  • Se houver suporte para A e B, o suplemento será ativado e toda a marcação no VersionOverrides> entrará em< vigor.
  • Se A tiver suporte, mas B não for, o suplemento será ativado e parte da marcação no VersionOverrides> entrará em< vigor. Especificamente, elementos filho dos <VersionOverrides que não substituem elementos> de manifesto base fazem efeito. Por exemplo, um <elemento WebApplicationInfo> ou um <EquivalentAddins> entrarão em vigor. No entanto, todos os elementos filho do <VersionOverrides> que substituem um elemento de manifesto base, como <Hosts>, não fazem efeito. Em vez disso, o Office usa os valores da marcação de manifesto base que, de outra forma, teriam sido substituídos.

Tipo de suplemento: Painel de tarefas, Email

Válido somente nestes esquemas VersionOverrides:

  • Painel de tarefas 1.0
  • Email 1.0
  • Email 1.1

Para obter mais informações, consulte Substituições de versão no manifesto.

Associado a esses conjuntos de requisitos:

Comentários

O <elemento Requisitos> não serve para nenhum propósito em um< VersionOverrides> se não especificar requisitos adicionais que não sejam especificados em um <Requisitos> no manifesto base. Se a versão e a plataforma do Office não dão suporte aos requisitos no manifesto base, o suplemento não será ativado e o <elemento VersionOverrides> não será analisado. Por esse motivo, você deve usar um <elemento Requirements> em um <VersionOverrides> somente quando ambas as condições forem atendidas:

  • Seu suplemento tem recursos extras que são implementados com configuração em um <VersionOverrides (como Comandos> de Suplemento) e que exigem um método ou conjunto de requisitos que não é especificado em um <elemento Requirements> no manifesto base.
  • Seu suplemento é útil e deve ser ativado (mas sem os recursos extras), mesmo em uma combinação de plataforma e versão do Office que não dá suporte aos requisitos necessários para os recursos extras.

Dica

Não repita elementos de requisito do manifesto base dentro de um <VersionOverrides>. Isso não tem efeito e é potencialmente enganoso quanto à finalidade do <elemento Requisitos> dentro de um <VersionOverrides>.

Aviso

Use muito cuidado antes de usar um <elemento Requirements> em um <VersionOverrides>, pois em combinações de plataforma e versão que não dão suporte ao requisito, nenhum dos comandos de suplemento será instalado, mesmo aqueles que invocam a funcionalidade que não precisa do requisito. Considere, por exemplo, um suplemento que tenha dois botões de faixa de opções personalizados. Uma delas chama APIs JavaScript do Office que estão disponíveis no conjunto de requisitos ExcelApi 1.4 (e posterior). As outras APIs de chamadas que só estão disponíveis no ExcelApi 1.9 (e posterior). Se você colocar um requisito para o <ExcelApi 1.9 no VersionOverrides>, quando 1.9 não tiver suporte nenhum botão aparecerá na faixa de opções. Uma estratégia melhor nesse cenário seria usar a técnica descrita em verificações do Runtime para o método e o suporte ao conjunto de requisitos. O código invocado pelo segundo botão usa primeiro isSetSupported para verificar o suporte do ExcelApi 1.9. Se não houver suporte, o código fornecerá ao usuário uma mensagem dizendo que esse recurso do suplemento não está disponível na versão do Office.

Observação

Em suplementos de email, é possível que um <VersionOverrides> 1.1 seja aninhado dentro de um <VersionOverrides> 1.0. O Office sempre usará a versão <mais alta VersionOverrides> com suporte da plataforma e da versão do Office.

Como filho do elemento Override

Um <elemento Requirements> pode ser filho de um elemento De substituição no contexto de um elemento ExtendedOverrides ancestral. Um <elemento Override> expressa um condicional e pode ser lido como um "Se ... então ..." Declaração. Se o <elemento Override> for do tipo RequirementTokenOverride (o que significa que o xsi:type do elemento token pai é RequirementsToken), o elemento Requisitos> filho< expressará a condição e o Value atributo será o conseqüente. Por exemplo, a primeira <Substituição> no seguinte é lida "Se a plataforma atual dá suporte ao FeatureOne versão 1.7, use a cadeia de caracteres 'oldAddinVersion' no lugar do ${token.requirements} token na URL do avô <ExtendedOverrides (em vez da cadeia de caracteres> padrão 'upgrade')." Para obter mais informações, consulte ExtendedOverrides.

<ExtendedOverrides Url="http://contoso.com/addinmetadata/${token.requirements}/extended-manifest-overrides.json">
    <Tokens>
        <Token Name="requirements" DefaultValue="upgrade" xsi:type="RequirementsToken">
            <Override Value="oldAddinVersion">
                <Requirements>
                    <Sets>
                        <Set Name="FeatureOne" MinVersion="1.7" />
                    </Sets>
                </Requirements>
            </Override>
            <Override Value="currentAddinVersion">
                <Requirements>
                    <Sets>
                        <Set Name="FeatureOne" MinVersion="1.8" />
                    </Sets>
                    <Methods>
                        <Method Name="MethodThree" />
                    </Methods>
                </Requirements>
            </Override>
        </Token>
    </Tokens>
</ExtendedOverrides>

Tipo de suplemento: Painel de tarefas

Sintaxe

<Requirements>
   ...
</Requirements>

Contido em

Pode conter

O <elemento Requisitos> pode conter os seguintes elementos filho, dependendo do tipo de suplemento.

Elemento Conteúdo Email TaskPane
Sets Sim Sim Sim
Métodos Sim Não Sim

Confira também

Para saber mais sobre os conjuntos de requisitos, confira Versões do Office e conjuntos de requisitos.