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. Pode implementar comandos de suplementos através do portal de aplicações integradas ou do Microsoft Marketplace ou utilizar o sideload para implementar 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:

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

  • O runtime é fechado quando a função é concluída ou passam 5 minutos, o que for anterior.

  • A função acionada pode chamar o método displayDialogAsync para mostrar uma caixa de diálogo. Esta é uma boa forma de apresentar um erro, mostrar o progresso ou pedir entrada ao utilizador.

    Observação

    Devido ao tempo limite de 5 minutos, a caixa de diálogo deve ser concebida para que os utilizadores concluam a interação e a fechem dentro de 5 minutos. O suplemento deve utilizar um painel de tarefas para interações mais longas.

  • Se o suplemento estiver configurado para utilizar um runtime partilhado, a função também pode chamar o método showAsTaskpane .

  Dica

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

  • Processadores personalizados para determinados eventos, como um utilizador que abre um novo painel de mensagens no Outlook.
  • Agentes Copilot personalizados que efetuam ações em resposta a pedidos de linguagem natural dos utilizadores do suplemento.

Localização dos comandos do suplemento

Quando um utilizador instala um suplemento, os comandos do suplemento encontram-se no friso, num separador incorporado do Office ou num separador personalizado especificado no manifesto. (Também pode colocar comandos de suplemento num separador contextual personalizado que o código do suplemento define no runtime.) Aparecem na IU como um botão ou um item num menu pendente.

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

No Office na Web, se estiver a utilizar o esquema de friso de linha única ou simplificado, o nome do suplemento não é apresentado no friso. Só é apresentado o ícone de comando do suplemento.

Excel, PowerPoint e Word

Segue-se um exemplo de comandos de suplemento num grupo personalizado no separador Dados do friso do Excel.

Outlook

Para o Outlook, quando quiser um comando de suplemento num separador incorporado do friso, em vez de criar o seu próprio, o comando será apresentado no separador predefinido com base na plataforma e no modo outlook atual. Para obter orientações, consulte Utilizar suplementos no Outlook.

Menu pendente

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

Comandos de suplemento agrupados no friso

Vários comandos de suplemento podem ser agrupados no friso. Um grupo tem de conter, pelo menos, um comando de suplemento sob a forma de um botão ou menu pendente. No Office no Windows e no Mac, a etiqueta e o ícone de um botão ou menu pendente são normalmente apresentados para comandos de suplementos num grupo. No entanto, o tamanho do ícone e a visibilidade da etiqueta podem variar devido aos seguintes fatores que restringem o espaço.

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

Se a janela do cliente estiver maximizada e existirem mais de três controlos num grupo, a etiqueta de cada controlo é apresentada, mas o tamanho do respetivo ícone pode variar (alguns são apresentados como 16 x 16 píxeis, enquanto outros são apresentados como 32 x 32 pixels).

Quando existem dois ou mais comandos de suplemento num grupo e o espaço fica limitado, são feitos os seguintes ajustes à forma como os comandos de suplemento são apresentados. Estas alterações são aplicadas aos grupos de comandos de suplemento da direita para a esquerda no friso na seguinte sequência.

1. São apresentados ícones pequenos (16 x 16 pixéis) e etiquetas para cada comando de suplemento num grupo.
2. Só são apresentados ícones pequenos.
3. O grupo é apresentado como um menu pendente em vez de mostrar comandos de suplemento individuais no friso. Também é apresentado um ícone de controlo de deslize de deslocamento no friso, para que possa percorrer o friso.

No Office na Web, o tamanho do ícone e a visibilidade da etiqueta dos controlos em grupos não mudam à medida que a janela do browser é redimensionada. O ícone do controlo de deslize de deslocamento é simplesmente apresentado no friso.

Recursos de comandos

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

Pontos de extensão

• Separadores do friso – expanda os separadores incorporados ou crie um novo separador de núcleo personalizado. Um suplemento pode ter apenas um separador de núcleo personalizado. (Também pode colocar comandos de suplemento num separador contextual personalizado.)

  Observação

  Para o Outlook, os separadores personalizados só são suportados no Outlook clássico no Windows. No Outlook na Web, no Mac e no novo Outlook no Windows, pode colocar grupos de controlos personalizados num dos separadores incorporados do friso.

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

Pode especificar se o comando está disponível quando o suplemento é iniciado e alterar a definição através de programação.

Observação

Esta funcionalidade não é suportada em todas as aplicações ou cenários do Office. Para obter mais informações, veja Alterar a disponibilidade dos comandos de suplementos.

Posição no friso

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

Pode especificar um separador contextual personalizado; ou seja, um separador que só é visível no friso 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 ligado a uma subscrição do Microsoft 365
• Office no Mac ligado a uma subscrição do Microsoft 365
• Office 2021 perpétua 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 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.

Melhores práticas para comandos de suplementos no friso

A tabela seguinte descreve os limites recomendados para objetos num friso de aplicação do Office.

Objeto	Limite recomendado	Lógica de utilização
Guias	Sete separadores visíveis de cada vez	Evita sobrecarregar os utilizadores com demasiadas opções e ajuda-os a lembrar-se onde estão localizados os comandos. Recomendamos a utilização de separadores contextuais para reduzir o correio secundário.
Grupos por separador	Seis grupos	Ajuda os utilizadores a analisar e localizar comandos rapidamente.
Comandos por grupo	Sete comandos	Diminui a fadiga da decisão de demasiadas opções.
Total de comandos no friso	70 comandos visíveis	Ajuda os utilizadores a localizar as ações de forma eficiente. Se o seu suplemento tiver mais de 70 comandos, recomendamos que implemente galerias, menus pendentes ou caixas de diálogo para capacidade excedida.

Além dos limites de objetos recomendados, tenha em atenção o seguinte ao configurar comandos de suplementos no friso.

• Coloque comandos num separador existente, como os separadores Inserir e Rever, 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 funcionar em todas as versões do Office (como Office na Web ou ambiente de trabalho) e um separador 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 fecham corretamente quando o tamanho da janela da aplicação do Office é alterado. Embora o friso ofereça redimensionamento dinâmico (veja Comandos de suplementos agrupados no friso), também tem de definir combinações de grupo para o seu suplemento.
• 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.
• Implemente uma caixa de diálogo para fornecer aos utilizadores opções avançadas. Isto impede que o suplemento sobrecarregue o friso com comandos raramente utilizados. Para saber como implementar uma caixa de diálogo, consulte Utilizar a API de caixa de diálogo do Office nos Suplementos do Office.

Observação

Os suplementos que ocupam demasiado espaço podem não passar na validação do Microsoft Marketplace.

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 apenas de suplemento, veja Criar comandos de suplementos com o manifesto apenas de suplemento 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.