Elemento FunctionFile

Especifica o arquivo de código-fonte para operações que um suplemento expõe de uma das seguintes maneiras.

• Comandos de suplemento que executam uma função JavaScript em vez de exibir a interface do usuário.
• Atalhos de teclado que executam uma função JavaScript.

Tipo de suplemento: Painel de tarefas, Email

Válido somente nestes esquemas VersionOverrides:

• Painel de tarefas 1.0
• Email 1.0
• Email 1.1

Para obter mais informações, consulte Substituições de versão no manifesto.

O <elemento FunctionFile> é um elemento filho de DesktopFormFactor ou MobileFormFactor. O resid atributo do <elemento FunctionFile> não pode ter mais de 32 caracteres e é definido como o valor do atributo de id um <elemento Url> no elemento Resources que contém a URL para um arquivo HTML que contém ou carrega todas as funções JavaScript usadas por botões de comando de função , conforme definido pelo elemento Control.

Observação

Quando o suplemento é configurado para usar um runtime compartilhado, as funções no arquivo de código são executadas no mesmo runtime do JavaScript (e compartilham um namespace global comum) que o JavaScript no painel de tarefas do suplemento (se houver).

O <elemento FunctionFile> e o arquivo de código associado também têm uma função especial a ser executada com atalhos de teclado personalizados, que exigem um runtime compartilhado.

A seguir está um exemplo do <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>

O JavaScript no arquivo HTML indicado pelo <elemento FunctionFile> deve inicializar Office.js e definir funções nomeadas que levem um único parâmetro: evento. Também devem chamar event.completed ao concluir a execução. As funções nos suplementos do Outlook devem usar as APIs de notificação para indicar progresso, êxito ou falha para o usuário. O nome das funções é usado no elemento FunctionName para botões de comando de função.

Você pode definir e registrar a função especificada pelo <elemento FunctionName> em um arquivo JavaScript separado carregado pelo arquivo HTML. A seguir está um exemplo desse arquivo.

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

A chamada para event.completed sinais de que você lidou com êxito com o evento. Quando uma função é chamada várias vezes, por exemplo, com vários cliques no mesmo comando de suplemento, todos os eventos são enfileirados automaticamente. O primeiro evento é executado automaticamente, enquanto os outros eventos permanecem na fila. Quando sua função chama event.completed, a próxima chamada na fila para essa função é executada. Você deve chamar event.completed; caso contrário, sua função não será executada.