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.

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:

  • O tempo de execução no qual o comando de função é executado é um tempo de execução completo baseado no navegador. Ele pode renderizar HTML e chamar a Internet para enviar ou obter dados.

  • O runtime fecha quando a função é concluída ou 5 minutos se passaram, o que ocorrer primeiro.

  • A função que é disparada pode chamar o método displayDialogAsync para mostrar uma caixa de diálogo. Essa é uma boa maneira de exibir um erro, mostrar o progresso ou solicitar a entrada do usuário.

    Observação

    Devido ao tempo limite de 5 minutos, a caixa de diálogo deve ser projetada para que os usuários concluam sua interação e fechem-na em 5 minutos. Seu suplemento deve usar um painel de tarefas para interações mais longas.

  • Se o suplemento estiver configurado para usar um runtime compartilhado, a função também poderá chamar o método showAsTaskpane .

  Dica

  Os comandos de função não são a única maneira de executar JavaScript arbitrário em um suplemento. Um suplemento também pode incluir:

  • Manipuladores personalizados para determinados eventos, como um usuário abrindo um novo painel de mensagens no Outlook.

Local dos comandos de suplemento

Quando um usuário instala um suplemento, os comandos do suplemento são encontrados na faixa de opções, em uma guia interna do Office ou em uma guia personalizada especificada no manifesto. (Você também pode colocar comandos de suplemento em uma guia contextual personalizada que o código do suplemento define em tempo de execução.) Eles aparecem na interface do usuário como um botão ou um item em um menu suspenso.

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

No Office na Web, se você estiver usando o layout de linha única ou faixa de opções simplificada, o nome do suplemento não será mostrado na faixa de opções. Somente o ícone de comando do suplemento é mostrado.

Excel, PowerPoint e Word

Veja a seguir um exemplo de comandos de suplemento em um grupo personalizado na guia Dados da faixa de opções do Excel.

Outlook

Para o Outlook, quando você deseja um comando de suplemento em uma guia interna da faixa de opções, em vez de criar o seu próprio, o comando aparecerá na guia padrão com base na plataforma e no modo atual do Outlook. Para obter orientação, consulte Usar suplementos no Outlook.

Menu suspenso

Um comando de suplemento de 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.

Comandos de suplemento agrupados na faixa de opções

Vários comandos de suplemento podem ser agrupados na faixa de opções. Um grupo deve conter pelo menos um comando de suplemento na forma de um botão ou de um menu suspenso. No Office no Windows e no Mac, o rótulo e o ícone de um botão ou menu suspenso geralmente são mostrados para comandos de suplemento em um grupo. No entanto, o tamanho do ícone e a visibilidade do rótulo podem variar devido aos seguintes fatores que restringem o espaço.

• O número de comandos de suplemento no grupo.
• O tamanho da janela do cliente Office.

Se a janela do cliente for maximizada e houver mais de três controles em um grupo, o rótulo de cada controle será mostrado, mas o tamanho de seu ícone poderá variar (alguns são mostrados como 16 x 16 pixels, enquanto outros são mostrados como 32 x 32 pixels).

Quando houver dois ou mais comandos de suplemento em um grupo e o espaço se tornar limitado, os seguintes ajustes serão feitos no modo como os comandos de suplemento são exibidos. Essas alterações são aplicadas aos grupos de comandos do suplemento da direita para a esquerda na faixa de opções na sequência a seguir.

1. Ícones pequenos (16 x 16 pixels) e rótulos são mostrados para cada comando de suplemento em um grupo.
2. Somente pequenos ícones são mostrados.
3. O grupo é exibido como um menu suspenso em vez de mostrar comandos de suplemento individuais na faixa de opções. Um ícone de controle deslizante de rolagem também aparece na faixa de opções, para que você possa rolar pela faixa de opções.

No Office na Web, o tamanho do ícone e a visibilidade do rótulo dos controles em grupos não são alterados à medida que a janela do navegador é redimensionada. O ícone do controle deslizante de rolagem é mostrado simplesmente na faixa de opções.

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 principal personalizada. Um suplemento pode ter apenas uma guia principal personalizada. (Você também pode colocar comandos do suplemento em uma guia contextual personalizada.)

  Observação

  Para o Outlook, as guias personalizadas só têm suporte no Outlook clássico no Windows. No Outlook na Web, no Mac e no novo Outlook no Windows, você pode colocar grupos personalizados de controles em uma das guias internas da faixa de opções.

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

Estado de disponibilidade padrão

Você pode especificar se o comando estará disponível quando o suplemento for iniciado e alterar a configuração de forma programática.

Posição na faixa de opções

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

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.

Guias contextuais

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

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 conectado a uma assinatura do Microsoft 365
• Office no Mac conectado a uma assinatura do Microsoft 365
• Perpétuo do Office 2021 ou posterior no Windows ou no Mac

Depurar

Para depurar um comando de suplemento, você deve 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 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 todos os ícones, siga as diretrizes de design de ícones.
• Forneça uma versão do seu suplemento que funcione em aplicativos ou plataformas do Office (como o iPad) que não dão suporte a comandos. Um único manifesto de suplemento pode ser usado para essas versões.

Práticas recomendadas para comandos de suplemento na faixa de opções

A tabela a seguir descreve os limites recomendados para objetos em uma faixa de opções do aplicativo do Office.

Além dos limites de objeto recomendados, lembre-se do seguinte ao configurar comandos de suplemento na faixa de opções.

• Coloque comandos em uma guia existente, como as guias Inserir e Revisão, se a funcionalidade fornecida couber nela. 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 poderá adicionar comandos à guia Página Inicial se o suplemento precisar funcionar em várias versões do Office (como o Office na Web ou na área de trabalho) e uma guia não estiver disponível em todas as versões.
• 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.
• Certifique-se de que os grupos sejam recolhidos normalmente quando o tamanho da janela do aplicativo do Office for alterado. Embora a faixa de opções ofereça redimensionamento dinâmico (confira Comandos de suplemento agrupados na faixa de opções), você também deve definir combinações de grupo para o suplemento.
• Não adicione botões desnecessários para aumentar o espaço do suplemento.
• Não posicione uma guia personalizada à esquerda da guia Página Inicial ou forneça foco a ela por padrão quando o documento for aberto, a menos que seu suplemento seja a principal maneira 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ó estiver 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.
• Implemente uma caixa de diálogo para fornecer aos usuários opções avançadas. Isso impede que o suplemento sobrecarregue a faixa de opções com comandos raramente usados. Para saber como implementar uma caixa de diálogo, consulte Usar a API de caixa de diálogo do Office em suplementos do Office.

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 somente de suplemento, consulte Criar comandos de suplemento com o manifesto somente de suplemento 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.