Criar comandos de suplemento com o manifesto XML

  • Artigo

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 seu manifesto XML para definir comandos de suplemento e como criar o código para comandos de função.

Dica

Para obter instruções sobre como criar comandos de suplemento com o manifesto unificado para o Microsoft 365, confira Criar comandos de suplemento com o manifesto unificado do Microsoft 365.

O diagrama a seguir mostra a hierarquia de elementos usada para definir comandos de suplemento. Descrevemos esses elementos com mais detalhes neste artigo.

Visão geral dos elementos de comandos de suplemento no manifesto. O nó superior aqui é VersionOverrides com hosts e recursos para crianças. Em Hosts estão Host e DesktopFormFactor. Em DesktopFormFactor estão FunctionFile e ExtensionPoint. Em ExtensionPoint estão CustomTab ou OfficeTab e Menu do Office. Em CustomTab ou Guia do Office estão o Grupo e, em seguida, Controlar a ação. Em Menu do Office estão Controle e Ação. Em Recursos (filho de VersionOverrides) estão Imagens, Urls, ShortStrings e LongStrings.

Comandos de exemplo

Todos os suplementos do painel de tarefas criados pelo Yo Office têm comandos de suplemento. Eles contêm um comando de suplemento (botão) 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. Verifique se você leu comandos de 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 <elemento VersionOverrides> é o elemento raiz que contém a definição do comando de suplemento. Os 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 <elemento VersionOverrides 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 <elemento Hosts> contém um ou mais <elementos Host>. Um <elemento Host> especifica um aplicativo específico do Office. O <elemento Host> contém elementos filho que especificam os comandos de suplemento a serem exibidos após a instalação do suplemento nesse aplicativo do Office. Para mostrar os mesmos comandos de suplemento em dois ou mais aplicativos diferentes do Office, você deve duplicar os elementos filho em cada <Host>.

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

O exemplo a seguir mostra os <elementos Hosts>, <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 <elemento FunctionFile> especifica um arquivo que contém código JavaScript a ser executado quando um comando de suplemento usa a ação ExecuteFunction. O <atributo resid do elemento FunctionFile> é definido como um arquivo HTML que inclui todos os arquivos JavaScript que seus comandos de suplemento exigem. Você não pode vincular diretamente a um arquivo JavaScript. Você só pode vincular a um arquivo HTML. O nome do arquivo é especificado como um <elemento Url> no <elemento Resources>.

Observação

Os projetos do Yo Office usam webpack para evitar adicionar manualmente o JavaScript ao HTML.

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>

Importante

Office.js deve ser inicializada antes que a lógica de comando do suplemento seja executada. Para obter mais informações, consulte Inicializar seu Suplemento do Office.

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. O processamento das notificações também deve ser definido em um arquivo HTML separado especificado no FunctionFile nó do manifesto.

Etapa 4: Adicionar elementos do ExtensionPoint

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

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

Importante

Forneça uma ID exclusiva para os elementos que contêm um atributo ID. Recomendamos usar o nome da sua empresa com a ID. Por exemplo, use o seguinte formato: <CustomTab id="mycompanyname.mygroupname">

<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>
      <Tooltip resid="residToolTip" />
      <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 <elemento Control> define a superfície utilizável do comando (botão, menu etc) 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. Pode ser a execução de uma função JavaScript ou a exibição de 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. No elemento Controle>:<

  • O atributo type é obrigatório e deve ser definido como Button.
  • O atributo id do <elemento Control> é uma cadeia de caracteres com no máximo 125 caracteres.
<!-- Define a control that calls a JavaScript function. -->
<Control xsi:type="Button" id="Button1Id1">
  <Label resid="residLabel" />
  <Tooltip resid="residToolTip" />
  <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" />
  <Tooltip resid="residToolTip" />
  <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>

O código a seguir mostra uma função de exemplo usada pelo <FunctionName>. Observe a chamada para event.completed. Isso sinaliza 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 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. 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);

Um controle de menu pode ser usado com PrimaryCommandSurface ou ContextMenu e define:

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

Quando usado com PrimaryCommandSurface, o item de menu raiz é exibido como um botão na faixa de opções. Quando o botão é selecionado, o submenu é exibido como uma lista suspensa. Quando usado com ContextMenu, um item de menu com um submenu é inserido no menu de contexto. Em ambos os casos, cada item de submenu pode executar uma função JavaScript 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. No elemento Controle>:<

  • 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" />
  <Tooltip resid="residToolTip" />
  <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>

Etapa 6: Adicionar o elemento Resources

O <elemento Resources> contém recursos usados pelos diferentes elementos filho do <elemento VersionOverrides>. 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.

O seguinte mostra um exemplo de como usar o <elemento Resources> . Cada recurso pode ter um ou mais <elementos filho de substituição> 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>

Observação

Você deve usar a SSL (Secure Sockets Layer) para todas as URLs nos <elementos Imagem> e <Url> .

Notas de suporte do Outlook

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

  • Outlook 2013 ou posterior no Windows
  • Outlook 2016 ou posterior no Mac
  • Outlook no iOS
  • Outlook no Android
  • Outlook na Web para o Exchange 2016 ou posterior
  • Outlook na Web para Microsoft 365 e Outlook.com
  • novo Outlook no Windows (versão prévia)

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

Se o suplemento usar um manifesto XML, os comandos de suplemento só estarão disponíveis para suplementos que não usam itemHasAttachment, ItemHasKnownEntity ou ItemHasRegularExpressionMatch para limitar os tipos de itens em que são ativados. No entanto, os suplementos contextuais podem apresentar comandos diferentes dependendo se o item selecionado atualmente é uma mensagem ou compromisso e podem optar por aparecer em cenários de leitura ou composição. É uma prática recomendada usar comandos de suplementos.

Confira também