FunctionFile-Element

Gibt die Quellcodedatei für Vorgänge an, die ein Add-In auf eine der folgenden Arten verfügbar macht.

• Add-In-Befehle, die eine JavaScript-Funktion ausführen, anstatt die Benutzeroberfläche anzuzeigen.
• Tastenkombinationen, die eine JavaScript-Funktion ausführen.

Add-In-Typ: Aufgabenbereich, E-Mail

Nur in den folgenden VersionOverrides-Schemas gültig:

• Aufgabenbereich 1.0
• Mail 1.0
• Mail 1.1

Weitere Informationen finden Sie unter Versionsüberschreibungen im Manifest.

Das <FunctionFile-Element> ist ein untergeordnetes Element von DesktopFormFactor oder MobileFormFactor. Das resid Attribut des <FunctionFile-Elements> darf nicht mehr als 32 Zeichen lang sein und ist auf den Wert des id Attributs eines <Url-Elements> im Resources-Element festgelegt, das die URL zu einer HTML-Datei enthält, die alle JavaScript-Funktionen enthält, die von Funktionsbefehlsschaltflächen verwendet werden, wie vom Control-Element definiert.

Hinweis

Wenn das Add-In für die Verwendung einer freigegebenen Runtime konfiguriert ist, werden die Funktionen in der Codedatei in derselben JavaScript-Runtime ausgeführt (und verwenden einen gemeinsamen globalen Namespace) wie JavaScript im Aufgabenbereich des Add-Ins (falls vorhanden).

Das <FunctionFile-Element> und die zugehörige Codedatei haben auch eine besondere Rolle bei benutzerdefinierten Tastenkombinationen, die eine freigegebene Laufzeit erfordern.

Es folgt ein Beispiel für das <FunctionFile-Element> .

<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>

Das JavaScript in der HTML-Datei, die durch das <FunctionFile-Element> angegeben wird, muss Office.jsinitialisieren und benannte Funktionen definieren, die einen einzelnen Parameter annehmen: event. Sie sollten auch event.completed aufrufen, wenn der Vorgang abgeschlossen ist. Funktionen in Outlook-Add-Ins sollten die Benachrichtigungs-APIs verwenden, um dem Benutzer Fortschritt, Erfolg oder Fehler anzuzeigen. Der Name der Funktionen wird im FunctionName-Element für Funktionsbefehlsschaltflächen verwendet.

Sie können die vom <FunctionName-Element> angegebene Funktion in einer separaten JavaScript-Datei definieren und registrieren, die von der HTML-Datei geladen wird. Es folgt ein Beispiel für eine solche Datei.

// 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);

Wichtig

Der Aufruf von event.completed signalisiert, dass Sie das Ereignis erfolgreich verarbeitet haben. Wird eine Funktion mehrmals aufgerufen, beispielsweise durch mehrere Klicks auf denselben Add-In-Befehl, werden alle Ereignisse automatisch in die Warteschlange gestellt. Das erste Ereignis wird automatisch ausgeführt, während die anderen Ereignisse in der Warteschlange verbleiben. Wenn Ihre Funktion aufruft event.completed, wird der nächste Aufruf dieser Funktion in der Warteschlange ausgeführt. Sie müssen aufrufen event.completed. Andernfalls wird Die Funktion nicht ausgeführt.