Élément FunctionFile

Spécifie le fichier de code source pour les opérations qu’un complément expose de l’une des manières suivantes.

• Commandes de complément qui exécutent une fonction JavaScript au lieu d’afficher l’interface utilisateur.
• Raccourcis clavier qui exécutent une fonction JavaScript.

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 du complément uniquement.

L’élément< FunctionFile> est un élément enfant de DesktopFormFactor ou MobileFormFactor. L’attribut resid de l’élément <FunctionFile> ne peut pas comporter plus de 32 caractères et est défini sur la valeur de l’attribut id d’un <élément Url> dans l’élément Resources qui contient l’URL d’un fichier HTML qui contient ou charge toutes les fonctions JavaScript utilisées par les boutons de commande de fonction , comme défini par l’élément Control.

Remarque

Lorsque le complément est configuré pour utiliser un runtime partagé, les fonctions du fichier de code s’exécutent dans le même runtime JavaScript (et partagent un espace de noms global commun) que le JavaScript dans le volet Office du complément (le cas échéant).

L’élément< FunctionFile> et le fichier de code associé ont également un rôle spécial à jouer avec les raccourcis clavier personnalisés, qui nécessitent un runtime partagé.

Voici un exemple de l’élément <FunctionFile> .

<DesktopFormFactor>
  <FunctionFile resid="Commands.Url" />
  <ExtensionPoint xsi:type="PrimaryCommandSurface">
    <!-- Information about this extension point. -->
  </ExtensionPoint>

  <!-- You can define more than one ExtensionPoint element as needed. -->
</DesktopFormFactor>

...

<Resources>
    <bt:Urls>
        <bt:Url id="Commands.Url" DefaultValue="https://www.contoso.com/commands.html" />
    </bt:Urls>

    <!-- Define other resources as needed. -->
</Resources>

Le code JavaScript dans le fichier HTML indiqué par l’élément <FunctionFile> doit initialiser Office.js et définir des fonctions nommées qui prennent un seul paramètre : événement. Il doit appeler également event.completed lorsque l’exécution est terminée. Les fonctions dans les compléments Outlook doivent utiliser les API de notification pour indiquer la progression, la réussite ou l’échec à l’utilisateur. Le nom des fonctions est utilisé dans l’élément FunctionName pour les boutons de commande de fonction.

Vous pouvez définir et inscrire la fonction spécifiée par l’élément <FunctionName> dans un fichier JavaScript distinct chargé par le fichier HTML. Voici un exemple de fichier de ce type.

// Initialize the Office Add-in.
Office.onReady(() => {
  // If needed, Office.js is ready to be called
});

// The command function.
async function highlightSelection(event) {

    // Implement your custom code here. The following code is a simple Excel example.  
    try {
          await Excel.run(async (context) => {
              const range = context.workbook.getSelectedRange();
              range.format.fill.color = "yellow";
              await context.sync();
          });
      } catch (error) {
          // Note: In a production add-in, notify the user through your add-in's UI.
          console.error(error);
      }

    // Calling event.completed is required. event.completed lets the platform know that processing has completed.
    event.completed();
}

// You must register the function with the following line.
Office.actions.associate("highlightSelection", highlightSelection);

Importante

L’appel à event.completed indique que vous avez géré l’événement avec succès. Lorsqu’une fonction est appelée à plusieurs reprises, par exemple lorsque l’utilisateur clique plusieurs fois sur une même commande de complément, tous les événements sont automatiquement mis en file d’attente. Le premier événement s’exécute automatiquement, tandis que les autres événements restent dans la file d’attente. Lorsque votre fonction appelle event.completed, l’appel en file d’attente suivant à cette fonction s’exécute. Vous devez appeler event.completed; sinon, votre fonction ne s’exécutera pas.