Comandos de suplemento

Comandos de suplemento são elementos de interface do usuário que estendem a interface do usuário do Office e iniciam ações no suplemento. Você pode usar comandos de suplemento para adicionar um botão à faixa de opções ou um item a um menu de contexto. Ao selecionar um comando de suplemento, os usuários iniciam ações como executar código JavaScript ou exibir uma página do suplemento em um painel de tarefas. Os comandos de suplemento ajudam os usuários a localizar e usar o suplemento, o que pode ajudá-lo a aumentar a adoção e a reutilização do suplemento, além de melhorar a retenção de clientes.

Observação

• Os catálogos do SharePoint não dão suporte a comandos de suplemento. Você pode implantar comandos de suplemento por meio de Aplicativos integrados ou do AppSourceou usar o sideload para implantar o comando de suplemento para teste.
• Atualmente os suplementos de conteúdo não dão suporte a comandos de suplemento.

Tipos de comandos de suplemento

Há dois tipos de comandos de suplemento, com base no tipo de ação que o comando dispara.

• Comandos do painel de tarefas: o botão ou o item do menu abre o painel de tarefas do suplemento. Você adiciona esse tipo de comando de suplemento com marcação no manifesto. O "código por trás" do comando é fornecido pelo Office.
• Comandos de função: O item de botão ou menu executa qualquer JavaScript arbitrário. O código quase sempre chama APIs na Biblioteca JavaScript do Office, mas não precisa. Esse tipo de suplemento normalmente não exibe nenhuma interface do usuário além do próprio item de menu ou botão. Observe o seguinte sobre comandos de função:
  • A função disparada pode chamar o método displayDialogAsync para mostrar uma caixa de diálogo, que é uma boa maneira de exibir um erro, mostrar o progresso ou solicitar a entrada do usuário. Se o suplemento estiver configurado para usar um runtime compartilhado, a função também poderá chamar o método showAsTaskpane .
  • O runtime no qual o comando da função é executado é um runtime completo baseado no navegador. Ele pode renderizar HTML e chamar a Internet para enviar ou obter dados.

Local dos comandos de suplemento

Quando um usuário instala um suplemento, o local de seus comandos depende do aplicativo, plataforma e contexto. Os comandos de suplemento são encontrados na faixa de opções, em uma guia padrão ou personalizada ou em uma barra de ações (só se aplica a determinadas plataformas do Outlook). Eles aparecem na interface do usuário como um botão ou um item em um menu suspenso.

Para comandos de suplemento que aparecem na faixa de opções, se você estiver usando o layout de faixa de opções simplificada, o nome do suplemento será removido da barra de aplicativos. Permanece apenas o botão de comando de suplemento na faixa de opções.

À medida que a faixa de opções ou a barra de ações fica mais lotada, os comandos de suplemento são exibidos no menu de estouro. Os comandos para o mesmo suplemento geralmente são agrupados.

Excel, PowerPoint e Word

A guia padrão depende do aplicativo e do contexto. Para Excel, PowerPoint e Word, a guia padrão é Home.

Outlook

Para o Outlook, o local padrão de um comando de suplemento é baseado na plataforma e no modo outlook atual. Para obter diretrizes, consulte Obter um suplemento do Office para o Outlook.

Menu suspenso

Um comando de suplemento do menu suspenso define uma lista estática de itens. O menu pode ser qualquer combinação de itens que executam uma função ou que abrem um painel de tarefas. Não há suporte para submenus.

Recursos de comandos

Os seguintes recursos de comando são compatíveis no momento.

Pontos de extensão

• Guias da Faixa de Opções - Estenda as guias internas ou crie uma nova guia personalizada. Um suplemento pode ter apenas uma guia personalizada.
• Menus de contexto: estender menus de contexto selecionados.

Tipos de controle

• Botões simples: disparar ações específicas.
• Menus – menu suspenso simples com botões que disparam ações.

Status padrão Habilitado ou Desabilitado

Você pode especificar se o comando está ativado ou desativado quando o suplemento é iniciado e alterar programaticamente a configuração.

Observação

Esse recurso não tem suporte em todos os aplicativos ou cenários do Office. Para obter mais informações, consulte Ativar e Desativar Comandos de Suplemento.

Posição na faixa de opções (visualização)

Você pode especificar onde uma guia personalizada é exibida na faixa de opções do aplicativo do Office, como "à direita da guia Página inicial".

Observação

Esse recurso não tem suporte em todos os aplicativos ou cenários do Office. Para saber mais, confira Posicionar uma guia personalizada na faixa de opções.

Integração de botões internos do Office

Você pode inserir os botões internos da faixa de opções do Office em seus grupos de comandos personalizados e na guia da faixa de opções personalizada.

Observação

Esse recurso não tem suporte em todos os aplicativos ou cenários do Office. Para saber mais, confira Integrar os botões internos do Office em guias personalizadas.

Guias contextuais

Você pode especificar que uma guia só seja visível na faixa de opções em determinados contextos, como quando um gráfico é selecionado no Excel.

Observação

Esse recurso não tem suporte em todos os aplicativos ou cenários do Office. Para obter mais informações, confira Criar guias contextuais personalizadas em Suplementos do Office.

Plataformas compatíveis

Os comandos de suplemento são atualmente suportados nas plataformas a seguir, exceto para limitações especificadas nas subseções de Recursos de comandos anteriores.

• Office no Windows (Build 16.0.6769 ou superior, conectado a uma assinatura do Microsoft 365)
• Office no Mac (build 15.33 ou superior, conectado a uma assinatura do Microsoft 365)
• Office na Web
• Office 2019 ou posterior no Windows ou Mac

Observação

Para obter informações sobre o suporte no Outlook, consulte notas de suporte do Outlook.

Depurar

Para depurar um comando de suplemento, você deve executá-lo em Office na Web. Para obter detalhes, confira Depurar suplementos no Office na Web.

Práticas recomendadas

Aplique as práticas recomendadas a seguir ao desenvolver comandos de suplemento.

• Use os comandos para representar uma ação específica com um resultado claro e específico para os usuários. Não combine várias ações em um único botão.

• Forneça ações granulares que tornam a realização de tarefas comuns no seu suplemento mais eficiente. Minimize o número de etapas necessárias para concluir uma tarefa.

• Para o posicionamento dos comandos na faixa de opções do Aplicativo do Office:

  • Coloque comandos em uma guia existente (Inserir, Revisar e assim por diante) se a funcionalidade fornecida se encaixar lá. Por exemplo, se o suplemento permitir que os usuários insiram mídia, adicione um grupo à guia Inserir. Observe que nem todas as guias estão disponíveis em todas as versões do Office. Para obter mais informações, consulte Manifesto de Suplementos do Office.
  • Insira comandos na guia Página Inicial se a funcionalidade não se encaixar em outra guia e você menos de seis comandos de nível superior. Você também pode adicionar comandos à guia Home se o suplemento precisar funcionar entre versões do Office (como Office na Web ou área de trabalho) e uma guia não estiver disponível em todas as versões (por exemplo, a guia Design não existe em Office na Web).
  • Coloque os comandos em uma guia personalizada se você tiver mais de seis comandos de nível superior.
  • Nomeie seu grupo de acordo com o nome do seu suplemento. Se você tiver vários grupos, nomeie cada grupo com base na funcionalidade que os comandos nesse grupo fornecem.
  • Não adicione botões desnecessários para aumentar o imóvel do seu suplemento.
  • Não posicione uma guia personalizada à esquerda da guia Home ou dê-lhe foco por padrão quando o documento for aberto, a menos que seu suplemento seja a maneira primária pela qual os usuários interagirão com o documento. Dar destaque excessivo as inconveniências do seu suplemento e incomodar os usuários e os administradores.
  • Se o seu suplemento for a principal maneira como os usuários interagem com o documento e você tiver uma guia personalizada na faixa de opções, considere integrar na guia os botões das funções do Office que os usuários frequentemente precisarão.
  • Se a funcionalidade fornecida com uma guia personalizada só deve estar disponível em determinados contextos, use guias contextuais personalizadas. Se você usar guias contextuais personalizadas, certifique-se de implementar uma experiência de fallback para quando o suplemento for executado em plataformas que não oferecem suporte a guias contextuais personalizadas.

  Observação

  Os suplementos que ocupam muito espaço podem não passar na Validação do AppSource.

• Para todos os ícones, siga as diretrizes de design de ícones.

• Forneça uma versão do suplemento que funciona em aplicativos ou plataformas do Office (como iPad) que não dão suporte a comandos. Um único manifesto de suplemento pode ser usado para essas versões.

Próximas etapas

A melhor maneira de começar a usar os comandos de suplemento é conferir os exemplos de comandos de Suplemento do Office no GitHub.

Para obter mais informações sobre como especificar comandos de suplemento em um manifesto XML, consulte Criar comandos de suplemento com o manifesto XML e o conteúdo de referência VersionOverrides .

Para obter mais informações sobre como especificar comandos de suplemento no manifesto unificado do Microsoft 365, consulte Criar comandos de suplemento com o manifesto unificado do Microsoft 365.