Élément Requirements

  • Article

La signification de cet élément varie selon qu’il est utilisé dans le manifeste de base, comme enfant d’un <élément VersionOverrides> ou comme enfant de l’élément Override.

Conseil

Avant d’utiliser cet élément, familiarisez-vous avec Spécifier les hôtes Office et les exigences d’API

Dans le manifeste de base

Lorsqu’il est utilisé dans le manifeste de base (c’est-à-dire en tant qu’enfant direct d’OfficeApp), l’élément <Requirements> spécifie l’ensemble minimal des exigences de l’API JavaScript Office (ensembles de conditions requises et/ou méthodes) que votre complément Office doit activer par Office. Le complément n’est activé sur aucune combinaison de version et de plateforme Office (par exemple, Windows, Mac, web, iOS ou iPad) qui ne prend pas en charge les méthodes et les ensembles de conditions requises spécifiés.

Type de complément : Volet Office, Courrier

En tant qu’enfant d’un élément VersionOverrides

Lorsqu’il est utilisé comme enfant de VersionOverrides, spécifie l’ensemble minimal des exigences de l’API JavaScript Office (ensembles de conditions requises et/ou méthodes) qui doit être pris en charge par la version et la plateforme Office (par exemple, Windows, Mac, web et iOS ou iPad) pour que les paramètres de l’élément <VersionOverrides>qui remplacent les paramètres du manifeste de base prennent effet.

Prenons l’exemple d’un complément qui spécifie l’exigence A dans le manifeste de base et la condition B à l’intérieur de <VersionOverrides>.

  • Si la plateforme et la version d’Office ne prennent pas en charge A, le complément n’est pas activé et Office n’analyse pas la <section VersionOverrides> du manifeste.
  • Si A et B sont pris en charge, le complément est activé et tout le balisage dans <VersionOverrides> prend effet.
  • Si A est pris en charge, mais que B ne l’est pas, le complément est activé et une partie du balisage dans VersionOverrides<> prend effet. Plus précisément, les <éléments enfants de VersionOverrides> qui ne remplacent pas les éléments de manifeste de base prennent effet. Par exemple, un <élément WebApplicationInfo> ou equivalentAddins<> prend effet. Toutefois, tous les éléments enfants de <VersionOverrides> qui remplacent un élément de manifeste de base, tel que <Hosts>, ne prennent pas effet. Au lieu de cela, Office utilise les valeurs du balisage de manifeste de base qui auraient autrement été remplacées.

Type de complément : Volet Office, Courrier

Valide uniquement dans les schémas VersionOverrides suivants :

  • Volet De tâches 1.0
  • Mail 1.0
  • Courrier 1.1

Pour plus d’informations, consultez Remplacements de version dans le manifeste.

Associé à ces ensembles de conditions requises :

Remarques

L’élément <Requirements> ne sert à rien dans versionOverrides<> s’il ne spécifie aucune exigence supplémentaire qui n’est pas spécifiée dans une <configuration Requise> dans le manifeste de base. Si la version et la plateforme d’Office ne prennent pas en charge les exigences du manifeste de base, le complément n’est pas activé et l’élément <VersionOverrides> n’est pas analysé. Pour cette raison, vous devez utiliser un <élément Requirements> dans versionOverrides<> uniquement lorsque les deux conditions suivantes sont remplies :

  • Votre complément possède des fonctionnalités supplémentaires implémentées avec la configuration dans versionOverrides<> (telles que les commandes de complément) et qui nécessitent une méthode ou un ensemble de conditions requises qui n’est pas spécifié dans un <élément Requirements> dans le manifeste de base.
  • Votre complément est utile et doit être activé (mais sans les fonctionnalités supplémentaires), même dans une combinaison de plateforme et de version d’Office qui ne prend pas en charge les exigences requises pour les fonctionnalités supplémentaires.

Conseil

Ne répétez pas les éléments Requirement du manifeste de base à l’intérieur d’une <versionOverrides>. Cela n’a aucun effet et est potentiellement trompeur quant à l’objectif de l’élément <Requirements> à l’intérieur d’une <versionOverrides>.

Avertissement

Soyez très prudent avant d’utiliser un <élément Requirements> dans versionOverrides<>, car sur les combinaisons de plateforme et de version qui ne prennent pas en charge la configuration requise, aucune commande de complément n’est installée, même celles qui appellent des fonctionnalités qui n’en ont pas besoin. Prenons l’exemple d’un complément doté de deux boutons de ruban personnalisés. L’un d’eux appelle les API JavaScript Office disponibles dans l’ensemble de conditions requises ExcelApi 1.4 (et versions ultérieures). L’autre appelle des API qui ne sont disponibles que dans ExcelApi 1.9 (et versions ultérieures). Si vous placez une exigence pour ExcelApi 1.9 dans VersionOverrides<>, lorsque la version 1.9 n’est pas prise en charge, aucun des boutons n’apparaît sur le ruban. Une meilleure stratégie dans ce scénario consisterait à utiliser la technique décrite dans Vérifications d’exécution pour la prise en charge des méthodes et des ensembles de conditions requises. Le code appelé par le deuxième bouton utilise isSetSupported d’abord pour vérifier la prise en charge d’ExcelApi 1.9. S’il n’est pas pris en charge, le code fournit à l’utilisateur un message indiquant que cette fonctionnalité du complément n’est pas disponible sur sa version d’Office.

Remarque

Dans les compléments de messagerie, il est possible qu’une <versionOverrides> 1.1 soit imbriquée à l’intérieur d’une <versionOverrides> 1.0. Office utilise toujours la version <la plus élevée VersionOverrides> qui est prise en charge par la plateforme et la version d’Office.

En tant qu’enfant de l’élément Override

Un <élément Requirements> peut être un enfant d’un élément Override dans le contexte d’un élément ExtendedOverrides ancêtre. Un <élément Override> exprime une condition et peut être lu en tant que « Si ... alors... » Déclaration. Si l’élément <Override> est de type RequirementsTokenOverride (ce qui signifie que le xsi:type de son élément Token parent est RequirementsToken), l’élément Requirements> enfant< exprime la condition, et l’attribut Value est la conséquence. Par exemple, le premier <remplacement> de l’article suivant est « Si la plateforme actuelle prend en charge FeatureOne version 1.7, utilisez la chaîne « oldAddinVersion » à la ${token.requirements} place du jeton dans l’URL du grand-parent< ExtendedOverrides> (au lieu de la chaîne par défaut « upgrade ») ». Pour plus d’informations, consultez 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>

Type de complément : volet Office

Syntaxe

<Requirements>
   ...
</Requirements>

Contenu dans

Peut contenir

L’élément <Requirements> peut contenir les éléments enfants suivants en fonction du type de complément.

Élément Contenu Courrier TaskPane
Ensembles Oui Oui Oui
Méthodes Oui Non Oui

Voir aussi

Pour plus d’informations concernant les ensembles de conditions requises, voir Versions d’Office et ensembles de conditions requises.