Elemento FunctionFile

Especifica el archivo de código fuente para las operaciones que expone un complemento de una de las siguientes maneras.

• Comandos de complemento que ejecutan una función de JavaScript en lugar de mostrar la interfaz de usuario.
• Métodos abreviados de teclado que ejecutan una función de JavaScript.

Tipo de complemento: Panel de tareas, Correo

Solo es válido en estos esquemas VersionOverrides:

• Panel de tareas 1.0
• Correo 1.0
• Correo 1.1

Para obtener más información, vea Invalidaciones de versión en el manifiesto.

El <elemento FunctionFile> es un elemento secundario de DesktopFormFactor o MobileFormFactor. El resid atributo del <elemento FunctionFile> no puede tener más de 32 caracteres y se establece en el valor del atributo de id un <elemento Url> en el elemento Resources que contiene la dirección URL de un archivo HTML que contiene o carga todas las funciones de JavaScript usadas por los botones de comando de función , tal como se define en el elemento Control.

Nota:

Cuando el complemento está configurado para usar un entorno de ejecución compartido, las funciones del archivo de código se ejecutan en el mismo entorno de ejecución de JavaScript (y comparten un espacio de nombres global común) que JavaScript en el panel de tareas del complemento (si existe).

El <elemento FunctionFile> y el archivo de código asociado también tienen un rol especial para jugar con métodos abreviados de teclado personalizados, que requieren un entorno de ejecución compartido.

A continuación se muestra un ejemplo del <elemento 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>

JavaScript en el archivo HTML indicado por el <elemento FunctionFile> debe inicializar Office.js y definir funciones con nombre que adoptan un único parámetro: event. También tiene que llamar a event.completed al finalizar la ejecución. Las funciones de los complementos de Outlook deben usar las API de notificación para indicar el progreso, el éxito o el error del usuario. El nombre de las funciones se usa en el elemento FunctionName para los botones de comando de función.

Puede definir y registrar la función especificada por el <elemento FunctionName> en un archivo JavaScript independiente cargado por el archivo HTML. A continuación se muestra un ejemplo de este tipo de archivo.

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

La llamada a event.completed indica que ha controlado correctamente el evento. Cuando se llama a una función varias veces, como puede ser haciendo varios clics en el mismo comando de complemento, se ponen automáticamente en cola de todos los eventos. El primer evento se ejecuta automáticamente, mientras que los demás eventos permanecen en la cola. Cuando la función llama a event.completed, se ejecuta la siguiente llamada en cola a esa función. Debe llamar a event.completed; de lo contrario, la función no se ejecutará.