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 suportam comandos de suplementos. 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 item de 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 utilizar um runtime partilhado, a função também pode chamar o método showAsTaskpane .
  • O runtime em que o comando da função é executado é um runtime completo baseado no browser. Ele pode renderizar HTML e chamar a Internet para enviar ou obter dados.

Localização dos comandos do suplemento

Quando um utilizador instala um suplemento, a localização dos respetivos comandos depende da aplicação, da plataforma e do contexto. Os comandos de suplemento encontram-se no friso, num separador predefinido ou personalizado, ou numa barra de ação (aplica-se apenas a determinadas plataformas do Outlook). Aparecem na IU como um botão ou um item num menu pendente.

Para comandos de suplementos que aparecem no friso, se estiver a utilizar o esquema de friso simplificado, o nome do suplemento é removido da barra de aplicações. Permanece apenas o botão de comando de suplemento na faixa de opções.

À medida que o friso ou a barra de ação fica mais cheio, os comandos de suplemento são apresentados no menu de capacidade excedida. Normalmente, os comandos para o mesmo suplemento são agrupados em conjunto.

Excel, PowerPoint e Word

O separador predefinido depende da aplicação e do contexto. Para o Excel, PowerPoint e Word, o separador predefinido é Base.

Outlook

Para o Outlook, a localização predefinida de um comando de suplemento baseia-se na plataforma e no modo outlook atual. Para obter orientações, consulte Utilizar suplementos no 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. Os submenus não são suportados.

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

Esta funcionalidade não é suportada em todas as aplicações 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

Esta funcionalidade não é suportada em todas as aplicações 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

Esta funcionalidade não é suportada em todas as aplicações 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

Esta funcionalidade não é suportada em todas as aplicações 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 na Web
• 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)
• Perpétuo Office 2019 ou posterior no Windows ou no 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, tem de executá-lo no 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 num ú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 num separador existente (Inserir, Rever, etc.) se a funcionalidade fornecida se ajustar. Por exemplo, se o suplemento permitir que os utilizadores insiram suportes de dados, adicione um grupo ao separador Inserir. Tenha em atenção que nem todos os separadores estão disponíveis em todas as versões do Office. Para obter mais informações, veja 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. Também pode adicionar comandos ao separador Base se o seu suplemento precisar de trabalhar em todas as versões do Office (como o Office na Web ou no ambiente de trabalho) e um separador não estiver disponível em todas as versões (por exemplo, o separador Estrutura não existe no 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 património do seu suplemento.
  • Não posicione um separador personalizado à esquerda do separador Base ou concentre-se por predefinição quando o documento for aberto, a menos que o seu suplemento seja a principal forma de os utilizadores interagirem 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 um separador personalizado só estiver disponível em determinados contextos, utilize separadores contextuais personalizados. 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 seu suplemento que funcione em aplicações ou plataformas do Office (como iPad) que não suportam comandos. Um único manifesto de suplemento pode ser utilizado para estas 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 suplementos num manifesto XML, veja Criar comandos de suplementos com o manifesto XML e o conteúdo de referência VersionOverrides .

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