Élément ControlControl element

Définit une fonction JavaScript qui exécute une action ou lance un volet Office. Un élément Control peut être une option de bouton ou de menu. Au moins un élément Control doit être inclus dans un élément Group.Defines a JavaScript function that executes an action or launches a task pane. A Control element can be either a button or a menu option. At least one Control must be included in a Group element.

AttributsAttributes

AttributAttribute ObligatoireRequired DescriptionDescription
xsi:typexsi:type OuiYes Type de contrôle défini. Peut être Button, Menu ou MobileButton.The type of control being defined. Can be either Button, Menu, or MobileButton.
idid NonNo ID de l’élément Control. Il doit comporter 125 caractères au maximum.The ID of the control element. Can be a maximum of 125 characters.

Notes

La valeur MobileButton de xsi:type est définie dans le schéma VersionOverrides 1.1.The MobileButton value for xsi:type is defined in VersionOverrides schema 1.1. Elle s’applique uniquement aux éléments Control contenus dans un élément MobileFormFactor.It only applies to the Control elements contained within a MobileFormFactor element.

Contrôle boutonButton control

Un bouton effectue une action unique quand il est sélectionné. Il peut exécuter une fonction ou afficher un volet Office. Chaque contrôle bouton doit avoir un id unique dans le manifeste.A button performs a single action when the user selects it. It can either execute a function or show a task pane. Each button control must have an id unique to the manifest.

Éléments enfantsChild elements

ÉlémentElement ObligatoireRequired DescriptionDescription
LabelLabel OuiYes Texte du bouton.The text for the button. L’attribut resid ne peut pas être plus de 32 caractères et doit être définie sur la valeur de l’attribut id d’un élément String dans l’élément ShortStrings dans l’élément Resources.The resid attribute can be no more than 32 characters and must be set to the value of the id attribute of a String element in the ShortStrings element in the Resources element.
ToolTipToolTip NonNo Info-bulle pour le bouton.The tooltip for the button. L’attribut resid ne peut pas être plus de 32 caractères et doit être définie sur la valeur de l’attribut id d’un élément String.The resid attribute can be no more than 32 characters and must be set to the value of the id attribute of a String element. String est un enfant de l’élément LongStrings, qui est lui-même un enfant de l’élément Resources.The String element is a child of the LongStrings element, which is a child of the Resources element.
SupertipSupertip OuiYes Info-bulle pour le bouton.The supertip for the button.
IconIcon OuiYes Image du bouton.An image for the button.
ActionAction OuiYes Spécifie l’action à effectuer.Specifies the action to perform.
EnabledEnabled NonNo Spécifie si le contrôle est activé au lancement du module.Specifies whether the control is enabled when the add-in launches.
OverriddenByRibbonApiOverriddenByRibbonApi NonNo Spécifie si le bouton doit apparaître sur les combinaisons d’applications et de plateformes qui prendre en charge les onglets contextuels personnalisés.Specifies whether the button should appear on application and platform combinations that support custom contextual tabs. S’il est utilisé, il doit s’agit du premier élément enfant.If used, it must be the first child element.

Exemple du bouton ExecuteFunctionExecuteFunction button example

Dans l’exemple suivant, le bouton est désactivé au lancement du module.In the following example, the button is disabled when the add-in launches. Il peut être activé par programme.It can be programmatically enabled. Pour plus d’informations, reportez-vous aux Commandes Activé et Désactivé pour les compléments.For more information, see Enable and Disable Add-in Commands.

<Control xsi:type="Button" id="msgReadFunctionButton">
  <OverriddenByRibbonApi>true</OverriddenByRibbonApi>
  <Label resid="funcReadButtonLabel" />
  <Supertip>
    <Title resid="funcReadSuperTipTitle" />
    <Description resid="funcReadSuperTipDescription" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="blue-icon-16" />
    <bt:Image size="32" resid="blue-icon-32" />
    <bt:Image size="80" resid="blue-icon-80" />
  </Icon>
  <Action xsi:type="ExecuteFunction">
    <FunctionName>getSubject</FunctionName>
  </Action>
  <Enabled>false</Enabled>
</Control>

Exemple du bouton ShowTaskpaneShowTaskpane button example

<Control xsi:type="Button" id="msgReadOpenPaneButton">
  <Label resid="paneReadButtonLabel" />
  <Supertip>
    <Title resid="paneReadSuperTipTitle" />
    <Description resid="paneReadSuperTipDescription" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="green-icon-16" />
    <bt:Image size="32" resid="green-icon-32" />
    <bt:Image size="80" resid="green-icon-80" />
  </Icon>
  <Action xsi:type="ShowTaskpane">
    <SourceLocation resid="readTaskPaneUrl" />
  </Action>
</Control>

Un menu définit une liste statique d’options. Chaque option de menu exécute une fonction ou affiche un volet Office. Les sous-menus ne sont pas pris en charge.A menu defines a static list of options. Each menu item either executes a function or shows a task pane. Submenus are not supported.

Lorsqu’il est utilisé avec un point d’extension PrimaryCommandSurface ou ContextMenu, le contrôle de menu définit les éléments suivants :When used with a PrimaryCommandSurface or ContextMenu extension point, the menu control defines:

  • une option de menu de niveau racine.A root-level menu item.

  • une liste de sous-menus.A list of submenu items.

Lorsqu’il est utilisé avec PrimaryCommandSurface, l’option de menu de niveau racine s’affiche sous la forme d’un bouton dans le ruban. Lorsque le bouton est sélectionné, le sous-menu s’affiche sous la forme d’une liste déroulante. Lorsqu’il est utilisé avec ContextMenu, un élément de menu avec un sous-menu est inséré dans le menu contextuel. Dans les deux cas, les éléments individuels du sous-menu peuvent exécuter une fonction JavaScript ou afficher un volet de tâches. Un seul niveau de sous-menus est pris en charge pour l’instant.When used with PrimaryCommandSurface, the root menu item displays as a button on the ribbon. When the button is selected, the submenu displays as a drop-down list. When used with ContextMenu, a menu item with a submenu is inserted on the context menu. In both cases, individual submenu items can either execute a JavaScript function or show a task pane. Only one level of submenus is supported at this time.

L’exemple suivant montre comment définir un élément de menu avec deux éléments de sous-menu. Le premier élément de sous-menu affiche un volet Office et le deuxième élément de sous-menu exécute une fonction JavaScript.The following example shows how to define a menu item with two submenu items. The first submenu item shows a task pane, and the second submenu item runs a JavaScript function.

<Control xsi:type="Menu" id="TestMenu2">
  <Label resid="residLabel3" />
  <Tooltip resid="residToolTip" />
  <Supertip>
    <Title resid="residLabel" />
    <Description resid="residToolTip" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="icon1_32x32" />
    <bt:Image size="32" resid="icon1_32x32" />
    <bt:Image size="80" resid="icon1_32x32" />
  </Icon>
  <Items>
    <Item id="showGallery2">
      <Label resid="residLabel3"/>
      <Supertip>
        <Title resid="residLabel" />
        <Description resid="residToolTip" />
      </Supertip>
      <Icon>
        <bt:Image size="16" resid="icon1_32x32" />
        <bt:Image size="32" resid="icon1_32x32" />
        <bt:Image size="80" resid="icon1_32x32" />
      </Icon>
      <Action xsi:type="ShowTaskpane">
        <TaskpaneId>MyTaskPaneID1</TaskpaneId>
        <SourceLocation resid="residUnitConverterUrl" />
      </Action>
    </Item>
    <Item id="showGallery3">
      <Label resid="residLabel5"/>
      <Supertip>
        <Title resid="residLabel" />
        <Description resid="residToolTip" />
      </Supertip>
      <Icon>
        <bt:Image size="16" resid="icon4_32x32" />
        <bt:Image size="32" resid="icon4_32x32" />
        <bt:Image size="80" resid="icon4_32x32" />
      </Icon>
      <Action xsi:type="ExecuteFunction">
        <FunctionName>getButton</FunctionName>
      </Action>
    </Item>
  </Items>
</Control>

Éléments enfantsChild elements

ÉlémentElement ObligatoireRequired DescriptionDescription
LabelLabel OuiYes Texte du bouton.The text for the button. L’attribut resid ne peut pas être plus de 32 caractères et doit être définie sur la valeur de l’attribut id d’un élément String dans l’élément ShortStrings dans l’élément Resources.The resid attribute can be no more than 32 characters and must be set to the value of the id attribute of a String element in the ShortStrings element in the Resources element.
ToolTipToolTip NonNo Info-bulle pour le bouton.The tooltip for the button. L’attribut resid ne peut pas être plus de 32 caractères et doit être définie sur la valeur de l’attribut id d’un élément String.The resid attribute can be no more than 32 characters and must be set to the value of the id attribute of a String element. String est un enfant de l’élément LongStrings, qui est lui-même un enfant de l’élément Resources.The String element is a child of the LongStrings element, which is a child of the Resources element.
SupertipSupertip OuiYes Info-bulle pour ce bouton.The supertip for this button.
IconIcon OuiYes Image du bouton.An image for the button.
ÉlémentsItems OuiYes Collection de boutons à afficher dans le menu.A collection of Buttons to display within the menu. Contient les éléments Élément pour chaque élément de sous-menu.Contains the Item elements for each submenu item. Chaque élément Item contient les éléments enfants du contrôle Bouton.Each Item element contains the child elements of the Button control.
OverriddenByRibbonApiOverriddenByRibbonApi NonNo Spécifie si le menu doit apparaître sur les combinaisons d’applications et de plateformes qui prendre en charge les onglets contextuels personnalisés.Specifies whether the menu should appear on application and platform combinations that support custom contextual tabs. S’il est utilisé, il doit s’agit du premier élément enfant.If used, it must be the first child element.
<Control xsi:type="Menu" id="TestMenu2">
  <OverriddenByRibbonApi>true</OverriddenByRibbonApi>
  <Label resid="residLabel3" />
  <Tooltip resid="residToolTip" />
  <Supertip>
    <Title resid="residLabel" />
    <Description resid="residToolTip" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="icon1_32x32" />
    <bt:Image size="32" resid="icon1_32x32" />
    <bt:Image size="80" resid="icon1_32x32" />
  </Icon>
  <Items>
    <Item id="showGallery2">
      <Label resid="residLabel3"/>
      <Supertip>
        <Title resid="residLabel" />
        <Description resid="residToolTip" />
      </Supertip>
      <Icon>
        <bt:Image size="16" resid="icon1_32x32" />
        <bt:Image size="32" resid="icon1_32x32" />
        <bt:Image size="80" resid="icon1_32x32" />
      </Icon>
      <Action xsi:type="ShowTaskpane">
        <TaskpaneId>MyTaskPaneID1</TaskpaneId>
        <SourceLocation resid="residUnitConverterUrl" />
      </Action>
    </Item>
    <Item id="showGallery3">
      <Label resid="residLabel5"/>
      <Supertip>
        <Title resid="residLabel" />
        <Description resid="residToolTip" />
      </Supertip>
      <Icon>
        <bt:Image size="16" resid="icon4_32x32" />
        <bt:Image size="32" resid="icon4_32x32" />
        <bt:Image size="80" resid="icon4_32x32" />
      </Icon>
      <Action xsi:type="ExecuteFunction">
        <FunctionName>getButton</FunctionName>
      </Action>
    </Item>
  </Items>
</Control>

<Control xsi:type="Menu" id="msgReadMenuButton">
  <Label resid="menuReadButtonLabel" />
  <Supertip>
    <Title resid="menuReadSuperTipTitle" />
    <Description resid="menuReadSuperTipDescription" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="red-icon-16" />
    <bt:Image size="32" resid="red-icon-32" />
    <bt:Image size="80" resid="red-icon-80" />
  </Icon>
  <Items>
    <Item id="msgReadMenuItem1">
      <OverriddenByRibbonApi>true</OverriddenByRibbonApi>
      <Label resid="menuItem1ReadLabel" />
      <Supertip>
        <Title resid="menuItem1ReadLabel" />
        <Description resid="menuItem1ReadTip" />
      </Supertip>
      <Icon>
        <bt:Image size="16" resid="red-icon-16" />
        <bt:Image size="32" resid="red-icon-32" />
        <bt:Image size="80" resid="red-icon-80" />
      </Icon>
      <Action xsi:type="ExecuteFunction">
        <FunctionName>getItemClass</FunctionName>
      </Action>
    </Item>
  </Items>
</Control>

Contrôle MobileButtonMobileButton control

Un bouton mobile effectue une action unique lorsque l’utilisateur le sélectionne. Il peut exécuter une fonction ou afficher un volet Office. Chaque contrôle de bouton mobile doit avoir un id unique dans le manifeste.A mobile button performs a single action when the user selects it. It can either execute a function or show a task pane. Each mobile button control must have an id unique to the manifest.

La valeur MobileButton de xsi:type est définie dans le schéma VersionOverrides 1.1. Pour les éléments VersionOverrides la contenant, l’attribut xsi:type doit avoir la valeur VersionOverridesV1_1.The MobileButton value for xsi:type is defined in VersionOverrides schema 1.1. The containing VersionOverrides element must have an xsi:type attribute value of VersionOverridesV1_1.

Éléments enfantsChild elements

ÉlémentElement ObligatoireRequired DescriptionDescription
LabelLabel OuiYes Texte du bouton.The text for the button. L’attribut resid ne peut pas être plus de 32 caractères et doit être définie sur la valeur de l’attribut id d’un élément String dans l’élément ShortStrings dans l’élément Resources.The resid attribute can be no more than 32 characters and must be set to the value of the id attribute of a String element in the ShortStrings element in the Resources element.
IconIcon OuiYes Image du bouton.An image for the button.
ActionAction OuiYes Spécifie l’action à effectuer.Specifies the action to perform.

Exemple de bouton mobile ExecuteFunctionExecuteFunction mobile button example

<Control xsi:type="MobileButton" id="msgReadFunctionButton">
  <Label resid="funcReadButtonLabel" />
  <Icon>
    <bt:Image resid="blue-icon-16-1" size="25" scale="1" />
    <bt:Image resid="blue-icon-16-2" size="25" scale="2" />
    <bt:Image resid="blue-icon-16-3" size="25" scale="3" />
    <bt:Image resid="blue-icon-32-1" size="32" scale="1" />
    <bt:Image resid="blue-icon-32-2" size="32" scale="2" />
    <bt:Image resid="blue-icon-32-3" size="32" scale="3" />
    <bt:Image resid="blue-icon-80-1" size="48" scale="1" />
    <bt:Image resid="blue-icon-80-2" size="48" scale="2" />
    <bt:Image resid="blue-icon-80-3" size="48" scale="3" />
  </Icon>
  <Action xsi:type="ExecuteFunction">
    <FunctionName>getSubject</FunctionName>
  </Action>
</Control>

Exemple de bouton mobile ShowTaskpaneShowTaskpane mobile button example

<Control xsi:type="MobileButton" id="msgReadOpenPaneButton">
  <Label resid="paneReadButtonLabel" />
  <Icon>
    <bt:Image resid="blue-icon-16-1" size="25" scale="1" />
    <bt:Image resid="blue-icon-16-2" size="25" scale="2" />
    <bt:Image resid="blue-icon-16-3" size="25" scale="3" />
    <bt:Image resid="blue-icon-32-1" size="32" scale="1" />
    <bt:Image resid="blue-icon-32-2" size="32" scale="2" />
    <bt:Image resid="blue-icon-32-3" size="32" scale="3" />
    <bt:Image resid="blue-icon-80-1" size="48" scale="1" />
    <bt:Image resid="blue-icon-80-2" size="48" scale="2" />
    <bt:Image resid="blue-icon-80-3" size="48" scale="3" />
  </Icon>
  <Action xsi:type="ShowTaskpane">
    <SourceLocation resid="readTaskPaneUrl" />
  </Action>
</Control>