Elemento FunctionFile

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

• Comandos de suplementos que executam uma função JavaScript em vez de apresentar a IU.
• Atalhos de teclado que executam uma função JavaScript.

Tipo de suplemento: Painel de tarefas, Correio

Válido apenas nestes esquemas VersionOverrides:

• Painel de tarefas 1.0
• Email 1.0
• Email 1.1

Para obter mais informações, veja Substituições de versões no manifesto apenas do suplemento.

O <elemento FunctionFile> é um elemento subordinado de DesktopFormFactor ou MobileFormFactor. O resid atributo do <elemento FunctionFile> não pode ter mais de 32 carateres e está definido para o valor do id atributo de um <elemento Url> no elemento Resources que contém o URL para um ficheiro HTML que contém ou carrega todas as funções JavaScript utilizadas pelos botões de comando de função , conforme definido pelo elemento Controlo.

Observação

Quando o suplemento está configurado para utilizar um runtime partilhado, as funções no ficheiro de código são executadas no mesmo runtime javaScript (e partilham um espaço de nomes global comum) que o JavaScript no painel de tarefas do suplemento (se aplicável).

O <elemento FunctionFile> e o ficheiro de código associado também têm uma função especial a desempenhar com atalhos de teclado personalizados, que requerem um runtime partilhado.

Segue-se 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 ficheiro HTML indicado pelo <elemento FunctionFile> tem de inicializar Office.js e definir funções nomeadas que assumem um único parâmetro: evento. Também devem chamar event.completed ao concluir a execução. As funções nos suplementos do Outlook devem utilizar as APIs de notificação para indicar o progresso, o sucesso ou a falha do utilizador. O nome das funções é utilizado no elemento FunctionName para botões de comando de função.

Pode definir e registar a função especificada pelo <elemento FunctionName> num ficheiro JavaScript separado que é carregado pelo ficheiro HTML. Segue-se um exemplo de tal ficheiro.

// 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 aos event.completed sinais de que lidou com o evento com êxito. 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 a função chama event.completed, a próxima chamada em fila para essa função é executada. Tem de chamar event.completed; caso contrário, a função não será executada.