Criar comandos de suplemento com o manifesto somente do suplemento

Os comandos de suplemento fornecem uma maneira fácil de personalizar a interface do usuário padrão do Office com elementos de interface do usuário especificados que executam ações. Para obter uma introdução aos comandos de suplemento, consulte Comandos de suplemento.

Este artigo descreve como editar o manifesto somente do suplemento para definir os comandos do suplemento e como criar o código para comandos de função.

O diagrama a seguir mostra a hierarquia de elementos usada para definir comandos do suplemento. Este artigo descreve esses elementos mais detalhadamente.

Comandos de amostra

Todos os suplementos do painel de tarefas criados pelo Yo Office têm comandos de suplemento. Elas contêm um comando (botão) de suplemento para mostrar o painel de tarefas. Gere esses projetos seguindo um dos inícios rápidos, como Criar um suplemento de painel de tarefas do Excel. Leia os comandos do suplemento para entender os recursos de comando.

Partes importantes de um comando de suplemento

As etapas a seguir explicam como adicionar comandos de suplemento a um suplemento existente.

Etapa 1: adicionar elemento VersionOverrides

O <VersionOverrides> elemento é o elemento raiz que contém a definição do comando do suplemento. Detalhes sobre os atributos e implicações válidos são encontrados em Substituições de versão no manifesto.

O exemplo a seguir mostra o <VersionOverrides> elemento e seus elementos filho.

<OfficeApp>
...
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
    <Requirements>
      <!-- Add information about requirement sets. -->
    </Requirements>
    <Hosts>
      <Host xsi:type="Workbook">
        <!-- Add information about form factors. -->
      </Host>
    </Hosts>
    <Resources> 
      <!-- Add information about resources. -->
    </Resources>
  </VersionOverrides>
...
</OfficeApp>

Etapa 2: adicionar elementos Hosts, Host e DesktopFormFactor

O <Hosts> elemento contém um ou mais <Host> elementos. Um <Host> elemento especifica um aplicativo específico do Office. O <Host> elemento contém elementos filho que especificam os comandos do suplemento a serem exibidos depois que o suplemento é instalado nesse aplicativo do Office. Para mostrar os mesmos comandos do suplemento em dois ou mais aplicativos diferentes do Office, você deve duplicar os elementos filho em cada um deles <Host>

O <DesktopFormFactor> elemento especifica as configurações de um suplemento que é executado no Office na Web, Windows e Mac.

O exemplo a seguir mostra os <Hosts>elementos , <Host>e <DesktopFormFactor> .

<OfficeApp>
...
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
  ...
    <Hosts>
      <Host xsi:type="Workbook">
        <DesktopFormFactor>

              <!-- Information about FunctionFile and ExtensionPoint. -->

        </DesktopFormFactor>
      </Host>
    </Hosts>
  ...
  </VersionOverrides>
...
</OfficeApp>

Etapa 3: adicionar o elemento FunctionFile

O <FunctionFile> elemento especifica um arquivo que contém código JavaScript ou TypeScript a ser executado quando um comando de suplemento usa a ação ExecuteFunction . O <FunctionFile> atributo resid do elemento é definido como um arquivo HTML que inclui todos os arquivos JavaScript ou TypeScript que os comandos de suplemento exigem. Não é possível vincular diretamente a um arquivo JavaScript ou TypeScript. Você só pode vincular a um arquivo HTML. O nome do arquivo é especificado como um <Url> elemento no <Resources> elemento.

A seguir está um exemplo do <FunctionFile> elemento.

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

Notificações do Outlook

Quando um suplemento precisa fornecer atualizações de status, como indicadores de progresso ou mensagens de erro, deve fazer isso por meio das APIs de notificação. Você também deve definir o processamento das notificações em um arquivo HTML separado especificado pelo FunctionFile nó do manifesto.

Etapa 4: adicionar elementos ExtensionPoint

O <ExtensionPoint> elemento define onde os comandos de suplemento devem aparecer na interface do usuário do Office.

Os exemplos a seguir mostram como usar o elemento com os valores de <ExtensionPoint> atributo PrimaryCommandSurface e ContextMenu e os elementos filho que devem ser usados com cada um.

<ExtensionPoint xsi:type="PrimaryCommandSurface">
  <CustomTab id="Contoso Tab">
  <!-- If you want to use a default tab that comes with Office, remove the above CustomTab element, and then uncomment the following OfficeTab element. -->
  <!-- <OfficeTab id="TabData"> -->
    <Label resid="residLabel4" />
    <Group id="Group1Id12">
      <Label resid="residLabel4" />
      <Icon>
        <bt:Image size="16" resid="icon1_32x32" />
        <bt:Image size="32" resid="icon1_32x32" />
        <bt:Image size="80" resid="icon1_32x32" />
      </Icon>
      <Control xsi:type="Button" id="Button1Id1">

        <!-- Information about the control. -->
      </Control>
      <!-- Other controls, as needed. -->
    </Group>
  </CustomTab>
</ExtensionPoint>
<ExtensionPoint xsi:type="ContextMenu">
  <OfficeMenu id="ContextMenuCell">
    <Control xsi:type="Menu" id="ContextMenu2">
            <!-- Information about the control. -->
    </Control>
    <!-- Other controls, as needed. -->
  </OfficeMenu>
</ExtensionPoint>

Etapa 5: adicionar elementos de controle

O <Control> elemento define a superfície utilizável do comando, como um botão ou menu, e a ação associada a ele.

Controles de botão

Um controle de botão executa uma única ação quando o usuário o seleciona. Ele pode executar uma função JavaScript ou TypeScript ou mostrar um painel de tarefas. O exemplo a seguir mostra como definir dois botões. O primeiro botão executa uma função JavaScript sem mostrar uma interface do usuário e o segundo botão mostra um painel de tarefas. <Control> No elemento:

• O atributo type é obrigatório e deve ser definido como Button.
• O atributo id do <Control> elemento é uma cadeia de caracteres com no máximo 125 caracteres.
• O atributo xsi:type do elemento filho <Action> deve ser definido como ExecuteFunction para executar uma função ou ShowTaskpane para exibir um painel de tarefas.

<!-- Define a control that calls a JavaScript function. -->
<Control xsi:type="Button" id="Button1Id1">
  <Label resid="residLabel" />
  <Supertip>
    <Title resid="residLabel" />
    <Description resid="residToolTip" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="icon1_32x32" />
    <bt:Image size="32" resid="icon1_32x32" />
    <bt:Image size="80" resid="icon1_32x32" />
  </Icon>
  <Action xsi:type="ExecuteFunction">
    <FunctionName>highlightSelection</FunctionName>
  </Action>
</Control>

<!-- Define a control that shows a task pane. -->
<Control xsi:type="Button" id="Button2Id1">
  <Label resid="residLabel2" />
  <Supertip>
    <Title resid="residLabel" />
    <Description resid="residToolTip" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="icon2_32x32" />
    <bt:Image size="32" resid="icon2_32x32" />
    <bt:Image size="80" resid="icon2_32x32" />
  </Icon>
  <Action xsi:type="ShowTaskpane">
    <SourceLocation resid="residUnitConverterUrl" />
  </Action>
</Control>

Controles de menu

Você pode usar um controle de menu com PrimaryCommandSurface ou ContextMenu. Ele define:

• Um item de menu no nível raiz.
• Uma lista de itens de submenu.

Quando você o usa com PrimaryCommandSurface, o item do menu raiz é exibido como um botão na faixa de opções. Quando o usuário seleciona o botão, o submenu é exibido como uma lista suspensa. Ao usá-lo com ContextMenu, um item de menu com um submenu é inserido no menu de contexto. Em ambos os casos, os itens de submenu individuais podem executar uma função JavaScript ou TypeScript ou mostrar um painel de tarefas. Somente há suporte para um nível de submenus no momento.

O exemplo a seguir mostra como definir um item de menu com dois itens de submenu. O primeiro item do submenu mostra um painel de tarefas e o segundo item executa uma função JavaScript. <Control> No elemento:

• O atributo xsi:type é obrigatório e deve ser definido como Menu.
• O atributo id é uma cadeia de caracteres com, no máximo, 125 caracteres.

<Control xsi:type="Menu" id="TestMenu2">
  <Label resid="residLabel3" />
  <Supertip>
    <Title resid="residLabel" />
    <Description resid="residToolTip" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="icon1_32x32" />
    <bt:Image size="32" resid="icon1_32x32" />
    <bt:Image size="80" resid="icon1_32x32" />
  </Icon>
  <Items>
    <Item id="showGallery2">
      <Label resid="residLabel3"/>
      <Supertip>
        <Title resid="residLabel" />
        <Description resid="residToolTip" />
      </Supertip>
      <Icon>
        <bt:Image size="16" resid="icon1_32x32" />
        <bt:Image size="32" resid="icon1_32x32" />
        <bt:Image size="80" resid="icon1_32x32" />
      </Icon>
      <Action xsi:type="ShowTaskpane">
        <TaskpaneId>MyTaskPaneID1</TaskpaneId>
        <SourceLocation resid="residUnitConverterUrl" />
      </Action>
    </Item>
    <Item id="showGallery3">
      <Label resid="residLabel5"/>
      <Supertip>
        <Title resid="residLabel" />
        <Description resid="residToolTip" />
      </Supertip>
      <Icon>
        <bt:Image size="16" resid="icon4_32x32" />
        <bt:Image size="32" resid="icon4_32x32" />
        <bt:Image size="80" resid="icon4_32x32" />
      </Icon>
      <Action xsi:type="ExecuteFunction">
        <FunctionName>getButton</FunctionName>
      </Action>
    </Item>
  </Items>
</Control>

Código de exemplo para comandos de função

O código a seguir mostra uma função invocada por um botão ou controle de item de menu cujo <Action>xsi:type do elemento está definido como ExecuteFunction. Observe o seguinte sobre o código.

• A chamada Office.actions.associate informa ao Office qual função executar quando um usuário seleciona um botão ou item de menu. O valor passado para seu parâmetro actionId deve corresponder ao <FunctionName> valor especificado no elemento do manifesto. Você deve ter uma Office.actions.associate chamada para cada comando de função definido no manifesto.
• A chamada event.completed sinaliza que seu código tratou 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 sua função chama event.completed, a próxima chamada em fila para essa função é executada. Você deve implementar event.completed, caso contrário, sua função não será executada.

// 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. The event.completed call lets the platform know that processing has completed.
    event.completed();
}

// This maps the function to the action ID specified in the manifest.
Office.actions.associate("highlightSelection", highlightSelection);

Etapa 6: Adicionar o elemento Resources

O <Resources> elemento contém recursos usados pelos diferentes elementos filho do <VersionOverrides> elemento. Resources inclui ícones, cadeias de caracteres e URLs. Um elemento no manifesto pode usar um recurso fazendo referência a id do recurso. O uso da id ajuda a organizar o manifesto, especialmente quando há versões diferentes do recurso para localidades diferentes. Uma id tem no máximo 32 caracteres.

Veja a seguir um exemplo de como usar o <Resources> elemento. Cada recurso pode ter um ou mais <Override> elementos filho para definir um recurso diferente para uma localidade específica.

<Resources>
  <bt:Images>
    <bt:Image id="icon1_16x16" DefaultValue="https://www.contoso.com/Images/icon_default.png">
      <bt:Override Locale="ja-jp" Value="https://www.contoso.com/Images/ja-jp16-icon_default.png" />
    </bt:Image>
    <bt:Image id="icon1_32x32" DefaultValue="https://www.contoso.com/Images/icon_default.png">
      <bt:Override Locale="ja-jp" Value="https://www.contoso.com/Images/ja-jp32-icon_default.png" />
    </bt:Image>
    <bt:Image id="icon1_80x80" DefaultValue="https://www.contoso.com/Images/icon_default.png">
      <bt:Override Locale="ja-jp" Value="https://www.contoso.com/Images/ja-jp80-icon_default.png" />
    </bt:Image>
  </bt:Images>
  <bt:Urls>
    <bt:Url id="residDesktopFuncUrl" DefaultValue="https://www.contoso.com/Pages/Home.aspx">
      <bt:Override Locale="ja-jp" Value="https://www.contoso.com/Pages/Home.aspx" />
    </bt:Url>
  </bt:Urls>
  <bt:ShortStrings>
    <bt:String id="residLabel" DefaultValue="GetData">
      <bt:Override Locale="ja-jp" Value="JA-JP-GetData" />
    </bt:String>
  </bt:ShortStrings>
  <bt:LongStrings>
    <bt:String id="residToolTip" DefaultValue="Get data for your document.">
      <bt:Override Locale="ja-jp" Value="JA-JP - Get data for your document." />
    </bt:String>
  </bt:LongStrings>
</Resources>

Notas de suporte do Outlook

Os comandos de suplemento estão disponíveis nas seguintes versões do Outlook.

• Outlook na Web para Microsoft 365 e Outlook.com
• Outlook na Web para o Exchange 2016 ou posterior
• novo Outlook no Windows
• Outlook 2016 ou posterior no Windows
• Outlook no Mac
• Outlook no Android
• Outlook no iOS

O suporte para comandos de suplementos no Exchange 2016 requer a Atualização Cumulativa 5.

Se o suplemento usar um manifesto somente do suplemento, os comandos do suplemento só estarão disponíveis para suplementos que não usam as regras ItemHasAttachment, ItemHasKnownEntity ou ItemHasRegularExpressionMatch para limitar os tipos de itens nos quais eles são ativados. No entanto, os suplementos contextuais podem apresentar comandos diferentes, dependendo se o item selecionado no momento é uma mensagem ou compromisso, e podem optar por aparecer em cenários de leitura ou redação. É uma prática recomendada usar comandos de suplementos.

Confira também

• Comandos de suplemento
• Exemplo: Criar um suplemento do Excel com botões de comando
• Exemplo: Criar um suplemento do Word com botões de comando
• Exemplo: Criar um suplemento do PowerPoint com botões de comando