Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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 suplementos, veja Comandos de suplementos.
Este artigo descreve como configurar o manifesto unificado do Microsoft 365 para definir comandos de suplementos e como criar o código para comandos de função.
Dica
As instruções para criar comandos de suplementos com o manifesto apenas de suplemento estão em Criar comandos de suplementos com o manifesto apenas de suplemento.
Observação
Para obter informações sobre clientes e plataformas que suportam Suplementos do Office que utilizam o manifesto unificado do Microsoft 365, consulte Suplementos do Office com o manifesto de aplicação unificada para o Microsoft 365.
Ponto de partida e passos principais
Ambas as ferramentas que criam projetos de suplemento com um manifesto unificado ( o gerador Yeoman do Office e o Toolkit de Agentes do Microsoft 365 - criam projetos com um ou mais comandos de suplemento. A única vez que ainda não terá um comando de suplemento é se estiver a atualizar um suplemento que anteriormente não tinha um.
Duas decisões
- Decida qual dos dois tipos de comandos de suplementos de que precisa: Painel de tarefas ou função
- Decida de que tipo de elemento de IU precisa: botão ou item de menu. Em seguida, execute os passos nas secções e subsecções abaixo que correspondem às suas decisões.
Comando Adicionar um painel de tarefas
As subsecções seguintes explicam como incluir um comando do painel de tarefas num suplemento.
Configurar o runtime para o comando do painel de tarefas
Abra o manifesto unificado e localize a
"extensions.runtimes"matriz.Certifique-se de que existe um objeto de runtime que tenha uma
"actions.type"propriedade com o valor"openPage". Este tipo de runtime abre um painel de tarefas.Certifique-se de que a
"requirements.capabilities"matriz contém um objeto que especifica um Conjunto de Requisitos que suporta comandos de suplementos. Para o Outlook, o requisito mínimo definido para comandos de suplementos é a Caixa de Correio 1.3. Para outras aplicações anfitriãs do Office, o requisito mínimo definido para comandos de suplemento é AddinCommands 1.1.Certifique-se de que o
"id"objeto do runtime tem um nome descritivo, como"TaskPaneRuntime".Certifique-se de que a
"code.page"propriedade do objeto de runtime está definida como o URL da página que deve abrir no painel de tarefas, como"https://localhost:3000/taskpane.html".Certifique-se de que o
"actions.view"objeto de runtime tem um nome que descreve o conteúdo da página que definiu no passo anterior, como"homepage"ou"dashboard".Certifique-se de que o
"actions.id"objeto de runtime tem um nome descritivo, como"ShowTaskPane", por exemplo, que indica o que acontece quando o utilizador seleciona o botão de comando ou item de menu do suplemento.Defina as outras propriedades e subpropriedades do objeto de runtime, conforme mostrado no exemplo concluído seguinte de um objeto de runtime. As
"type"propriedades e"lifetime"são necessárias e nos Suplementos do Outlook. Têm sempre os valores apresentados neste exemplo."runtimes": [ { "requirements": { "capabilities": [ { "name": "Mailbox", "minVersion": "1.3" } ] }, "id": "TaskPaneRuntime", "type": "general", "code": { "page": "https://localhost:3000/taskpane.html" }, "lifetime": "short", "actions": [ { "id": "ShowTaskPane", "type": "openPage", "view": "homepage" } ] } ]
Configurar a IU para o comando do painel de tarefas
Certifique-se de que o objeto de extensão para o qual configurou um runtime tem uma
"ribbons"propriedade de matriz como elemento da rede para a"runtimes"matriz. Normalmente, existe apenas um objeto de extensão na"extensions"matriz.Certifique-se de que a matriz tem um objeto com propriedades de matriz com o nome
"contexts"e"tabs", conforme mostrado no exemplo seguinte."ribbons": [ { "contexts": [ // child objects omitted ], "tabs": [ // child objects omitted ] } ]Certifique-se de que a
"contexts"matriz tem cadeias que especificam as janelas ou painéis nos quais a IU do comando do painel de tarefas deve ser apresentada. Por exemplo,"mailRead"significa que será apresentada no painel de leitura ou janela de mensagens quando uma mensagem de e-mail estiver aberta, mas"mailCompose"significa que será apresentada quando uma nova mensagem ou resposta estiver a ser composta. Seguem-se os valores permitidos:"mailRead""mailCompose""meetingDetailsOrganizer""meetingDetailsAttendee"
Apresentamos um exemplo a seguir.
"contexts": [ "mailRead" ],Certifique-se de que a
"tabs"matriz tem um objeto com uma"builtInTabId"propriedade de cadeia definida como o ID do separador do friso no qual pretende que o comando do painel de tarefas seja apresentado. Além disso, certifique-se de que existe uma"groups"matriz com, pelo menos, um objeto. Apresentamos um exemplo a seguir."tabs": [ { "builtInTabID": "TabDefault", "groups": [ { // properties omitted } ] } ]Observação
Para obter uma lista dos valores possíveis da
"builtInTabID"propriedade, consulte Localizar os IDs dos separadores incorporados do friso do Office.Certifique-se de que a
"groups"matriz tem um objeto para definir o grupo de controlo personalizado que irá conter os controlos de IU do comando do suplemento. Apresentamos um exemplo a seguir. Tenha em atenção o seguinte sobre este JSON:- O
"id"tem de ser exclusivo em todos os grupos em todos os objetos do friso no manifesto. O comprimento máximo é de 64 caracteres. - É
"label"apresentado no grupo no friso. Embora o comprimento máximo seja de 64 carateres, para garantir que o grupo de controlo se encaixa corretamente no friso, recomendamos que limite o"label"a 16 carateres. - Um dos
"icons"aparece no grupo apenas se a janela da aplicação do Office e, por conseguinte, o friso tiver sido dimensionado pelo utilizador demasiado pequeno para que qualquer um dos controlos no grupo seja apresentado. O Office decide quando utilizar um destes ícones e qual utilizar com base no tamanho da janela e na resolução do dispositivo. Não pode controlar isto. Tem de fornecer ficheiros de imagem para 16, 32 e 80 píxeis, enquanto outros cinco tamanhos também são suportados (20, 24, 40, 48 e 64 pixels). Tem de utilizar Secure Sockets Layer (SSL) para todos os URLs.
"groups": [ { "id": "msgReadGroup", "label": "Contoso Add-in", "icons": [ { "size": 16, "url": "https://localhost:3000/assets/icon-16.png" }, { "size": 32, "url": "https://localhost:3000/assets/icon-32.png" }, { "size": 80, "url": "https://localhost:3000/assets/icon-80.png" } ], "controls": [ { // properties omitted } ] } ]- O
Certifique-se de que existe um objeto de controlo na
"controls"matriz para cada botão ou menu personalizado que pretende. Apresentamos um exemplo a seguir. Tenha em atenção o seguinte sobre este JSON:- As
"id"propriedades ,"label"e"icons"têm a mesma finalidade e as mesmas restrições que as propriedades correspondentes de um objeto de grupo, exceto que se aplicam a um botão ou menu específico dentro do grupo. - A
"type"propriedade está definida para"button"o que significa que o controlo será um botão do friso. Também pode configurar um comando do painel de tarefas para ser executado a partir de um item de menu. Consulte Menu e itens de menu. - O
"supertip.title"(comprimento máximo: 64 carateres) e"supertip.description"(comprimento máximo: 128 carateres) aparecem quando o cursor está a pairar sobre o botão ou menu. - O
"actionId"tem de ser uma correspondência exata para o"runtimes.actions.id"que definiu em Configurar o runtime para o comando do painel de tarefas.
{ "id": "msgReadOpenPaneButton", "type": "button", "label": "Show Task Pane", "icons": [ { "size": 16, "url": "https://localhost:3000/assets/icon-16.png" }, { "size": 32, "url": "https://localhost:3000/assets/icon-32.png" }, { "size": 80, "url": "https://localhost:3000/assets/icon-80.png" } ], "supertip": { "title": "Show Contoso Task Pane", "description": "Opens the Contoso task pane." }, "actionId": "ShowTaskPane" }- As
Concluiu a adição de um comando do painel de tarefas ao seu suplemento. Faça sideload e teste-o.
Adicionar um comando de função
As subsecções seguintes explicam como incluir um comando de função num suplemento.
Criar o código para o comando de função
Certifique-se de que o código fonte inclui um ficheiro JavaScript ou Typescript com a função que pretende executar com o comando de função. Apresentamos um exemplo a seguir. Uma vez que este artigo se trata de criar comandos de suplementos e não de ensinar a Biblioteca JavaScript do Office, fornecemos-lhe comentários mínimos, mas repare no seguinte:
- Para efeitos deste artigo, o ficheiro tem o nome commands.js.
- A função fará com que seja apresentada uma pequena notificação numa mensagem de e-mail aberta com o texto "Ação executada".
- Como todo o código que chama APIs na Biblioteca JavaScript do Office, tem de começar por inicializar a biblioteca. Efetua este procedimento ao chamar
Office.onReady. - A última coisa que o código chama é Office.actions.associate para indicar ao Office que função no ficheiro deve ser executada quando a IU do comando da sua função é invocada. A função mapeia o nome da função para um ID de ação que configura no manifesto num passo posterior. Se definir vários comandos de função no mesmo ficheiro, o código tem de chamar
associatecada um deles. - A função tem de utilizar um parâmetro do tipo Office.AddinCommands.Event. A última linha da função tem de chamar event.completed.
Office.onReady(function() { // Add any initialization code here. }); function setNotification(event) { const message = { type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage, message: "Performed action.", icon: "Icon.80x80", persistent: true, }; // Show a notification message. Office.context.mailbox.item.notificationMessages.replaceAsync("ActionPerformanceNotification", message); // Be sure to indicate when the add-in command function is complete. event.completed(); } // Map the function to the action ID in the manifest. Office.actions.associate("SetNotification", setNotification);Certifique-se de que o código fonte inclui um ficheiro HTML configurado para carregar o ficheiro de função que criou. Apresentamos um exemplo a seguir. Tenha em atenção o seguinte sobre este JSON:
Para efeitos deste artigo, o ficheiro tem o nome commands.html.
O
<body>elemento está vazio porque o ficheiro não tem IU. O seu único objetivo é carregar ficheiros JavaScript.A Biblioteca JavaScript do Office e o ficheiro commands.js que criou no passo anterior são explicitamente carregados.
Observação
É comum no desenvolvimento de Suplementos do Office utilizar ferramentas como o webpack e os respetivos plug-ins para injetar
<script>automaticamente etiquetas em ficheiros HTML no momento da compilação. Se utilizar essa ferramenta, não deve incluir<script>etiquetas no ficheiro de origem que serão inseridas pela ferramenta.
<!DOCTYPE html> <html> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> <!-- Office JavaScript Library --> <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script> <!-- Function command file --> <script src="commands.js" type="text/javascript"></script> </head> <body> </body> </html>
Configurar o runtime para o comando de função
Abra o manifesto unificado e localize a
"extensions.runtimes"matriz.Certifique-se de que existe um objeto de runtime que tenha uma
"actions.type"propriedade com o valor"executeFunction".Certifique-se de que a
"requirements.capabilities"matriz contém objetos que especificam quaisquer Conjuntos de Requisitos necessários para suportar os comandos de suplemento de APIs. Para o Outlook, o requisito mínimo definido para comandos de suplementos é a Caixa de Correio 1.3. No entanto, se o comando da função chamar essa API que faz parte do conjunto de requisitos da Caixa de Correio posterior, como a Caixa de Correio 1.5, terá de especificar a versão posterior (por exemplo, "1,5") como o"minVersion"valor. Para outras aplicações anfitriãs do Office, o requisito mínimo definido para comandos de suplemento é AddinCommands 1.1.Certifique-se de que o
"id"objeto de runtime tem um nome descritivo, como "CommandsRuntime".Certifique-se de que a
"code.page"propriedade do objeto runtime está definida para o URL da página HTML sem IU que carrega o ficheiro de função, como"https://localhost:3000/commands.html".Certifique-se de que o
"actions.id"objeto de runtime tem um nome descritivo, como "SetNotification", que indica o que acontece quando o utilizador seleciona o botão de comando ou item de menu do suplemento.Importante
O valor de
"actions.id"tem de corresponder exatamente ao primeiro parâmetro da chamada paraOffice.actions.associateno ficheiro de função.Defina as outras propriedades e subpropriedades do objeto de runtime, conforme mostrado no exemplo concluído seguinte de um objeto de runtime.
"runtimes": [ { "id": "CommandsRuntime", "type": "general", "code": { "page": "https://localhost:3000/commands.html" }, "lifetime": "short", "actions": [ { "id": "SetNotification", "type": "executeFunction", } ] } ]
Configurar a IU para o comando de função
Certifique-se de que o objeto de extensão para o qual configurou um runtime tem uma
"ribbons"propriedade de matriz como elemento da rede para a"runtimes"matriz. Normalmente, existe apenas um objeto de extensão na"extensions"matriz.Certifique-se de que a matriz tem um objeto com propriedades de matriz com o nome
"contexts"e"tabs", conforme mostrado no exemplo seguinte."ribbons": [ { "contexts": [ // child objects omitted ], "tabs": [ // child objects omitted ] } ]Certifique-se de que a
"contexts"matriz tem cadeias que especificam as janelas ou painéis nos quais a IU do comando de função deve ser apresentada. Por exemplo,"mailRead"significa que será apresentada no painel de leitura ou janela de mensagens quando uma mensagem de e-mail estiver aberta, mas"mailCompose"significa que será apresentada quando uma nova mensagem ou resposta estiver a ser composta. Seguem-se os valores permitidos:"mailRead""mailCompose""meetingDetailsOrganizer""meetingDetailsAttendee"
Apresentamos um exemplo a seguir.
"contexts": [ "mailRead" ],Certifique-se de que a matriz tem um objeto com uma
"builtInTabId"propriedade de cadeia definida como o ID do separador do friso no qual pretende que o"tabs"comando da função seja apresentado e uma"groups"matriz com, pelo menos, um objeto. Apresentamos um exemplo a seguir."tabs": [ { "builtInTabID": "TabDefault", "groups": [ { // properties omitted } ] } ]Observação
Para obter uma lista dos valores possíveis da
"builtInTabID"propriedade, consulte Localizar os IDs dos separadores incorporados do friso do Office.Certifique-se de que a
"groups"matriz tem um objeto para definir o grupo de controlo personalizado que irá conter os controlos de IU do comando do suplemento. Apresentamos um exemplo a seguir. Tenha em atenção o seguinte sobre este JSON:- O
"id"tem de ser exclusivo em todos os grupos em todos os objetos do friso no manifesto. O comprimento máximo é de 64 caracteres. - É
"label"apresentado no grupo no friso. Embora o comprimento máximo seja de 64 carateres, para garantir que o grupo de controlo se encaixa corretamente no friso, recomendamos que limite o"label"a 16 carateres. - Um dos
"icons"aparece no grupo apenas se a janela da aplicação do Office e, por conseguinte, o friso tiver sido dimensionado pelo utilizador demasiado pequeno para que qualquer um dos controlos no grupo seja apresentado. O Office decide quando utilizar um destes ícones e qual utilizar com base no tamanho da janela e na resolução do dispositivo. Não pode controlar isto. Tem de fornecer ficheiros de imagem para 16, 32 e 80 píxeis, enquanto outros cinco tamanhos também são suportados (20, 24, 40, 48 e 64 pixels). Tem de utilizar Secure Sockets Layer (SSL) para todos os URLs.
"groups": [ { "id": "msgReadGroup", "label": "Contoso Add-in", "icons": [ { "size": 16, "url": "https://localhost:3000/assets/icon-16.png" }, { "size": 32, "url": "https://localhost:3000/assets/icon-32.png" }, { "size": 80, "url": "https://localhost:3000/assets/icon-80.png" } ], "controls": [ { // properties omitted } ] } ]- O
Certifique-se de que existe um objeto de controlo na
"controls"matriz para cada botão ou menu personalizado que pretende. Apresentamos um exemplo a seguir. Tenha em atenção o seguinte sobre este JSON:- As
"id"propriedades ,"label"e"icons"têm a mesma finalidade e as mesmas restrições que as propriedades correspondentes de um objeto de grupo, exceto que se aplicam a um botão ou menu específico dentro do grupo. - A
"type"propriedade está definida para"button"o que significa que o controlo será um botão do friso. Também pode configurar um comando de função para ser executado a partir de um item de menu. Consulte Menu e itens de menu. - O
"supertip.title"(comprimento máximo: 64 carateres) e"supertip.description"(comprimento máximo: 128 carateres) aparecem quando o cursor está a pairar sobre o botão ou menu. - O
"actionId"tem de ser uma correspondência exata para o"runtime.actions.id"que definiu em Configurar o runtime para o comando da função.
{ "id": "msgReadSetNotificationButton", "type": "button", "label": "Set Notification", "icons": [ { "size": 16, "url": "https://localhost:3000/assets/icon-16.png" }, { "size": 32, "url": "https://localhost:3000/assets/icon-32.png" }, { "size": 80, "url": "https://localhost:3000/assets/icon-80.png" } ], "supertip": { "title": "Set Notification", "description": "Displays a notification message on the current message." }, "actionId": "SetNotification" }- As
Concluiu a adição de um comando de função ao suplemento. Faça sideload e teste-o.
Menu e itens de menu
Além dos botões personalizados, também pode adicionar menus pendentes personalizados ao friso do Office. Esta secção explica como utilizar um exemplo com dois itens de menu. Um invoca um comando do painel de tarefas. O outro invoca um comando de função.
Configurar os runtimes e o código
Execute os passos das seguintes secções:
- Configurar o runtime para o comando do painel de tarefas
- Criar o código para o comando de função
- Configurar o runtime para o comando de função
Configurar a IU para o menu
Certifique-se de que o objeto de extensão para o qual configurou um runtime tem uma
"ribbons"propriedade de matriz como elemento da rede para a"runtimes"matriz. Normalmente, existe apenas um objeto de extensão na"extensions"matriz.Certifique-se de que a matriz tem um objeto com propriedades de matriz com o nome
"contexts"e"tabs", conforme mostrado no exemplo seguinte."ribbons": [ { "contexts": [ // child objects omitted ], "tabs": [ // child objects omitted ] } ]Certifique-se de que a
"contexts"matriz tem cadeias que especificam as janelas ou painéis nos quais o menu deve aparecer no friso. Por exemplo,"mailRead"significa que será apresentada no painel de leitura ou janela de mensagens quando uma mensagem de e-mail estiver aberta, mas"mailCompose"significa que será apresentada quando uma nova mensagem ou resposta estiver a ser composta. Seguem-se os valores permitidos:"mailRead""mailCompose""meetingDetailsOrganizer""meetingDetailsAttendee"
Apresentamos um exemplo a seguir.
"contexts": [ "mailRead" ],Certifique-se de que a
"tabs"matriz tem um objeto com uma"builtInTabId"propriedade de cadeia definida para o ID do separador do friso no qual pretende que o comando do painel de tarefas seja apresentado e uma"groups"matriz com, pelo menos, um objeto. Apresentamos um exemplo a seguir."tabs": [ { "builtInTabID": "TabDefault", "groups": [ { // properties omitted } ] } ]Observação
Para obter uma lista dos valores possíveis da
"builtInTabID"propriedade, consulte Localizar os IDs dos separadores incorporados do friso do Office.Certifique-se de que a
"groups"matriz tem um objeto para definir o grupo de controlo personalizado que irá manter o controlo de menu pendente. Apresentamos um exemplo a seguir. Tenha em atenção o seguinte sobre este JSON:- O
"id"tem de ser exclusivo em todos os grupos em todos os objetos do friso no manifesto. O comprimento máximo é de 64 caracteres. - É
"label"apresentado no grupo no friso. Embora o comprimento máximo seja de 64 carateres, para garantir que o grupo de controlo se encaixa corretamente no friso, recomendamos que limite o"label"a 16 carateres. - Um dos
"icons"aparece no grupo apenas se a janela da aplicação do Office e, por conseguinte, o friso tiver sido dimensionado pelo utilizador demasiado pequeno para que qualquer um dos controlos no grupo seja apresentado. O Office decide quando utilizar um destes ícones e qual utilizar com base no tamanho da janela e na resolução do dispositivo. Não pode controlar isto. Tem de fornecer ficheiros de imagem para 16, 32 e 80 píxeis, enquanto outros cinco tamanhos também são suportados (20, 24, 40, 48 e 64 pixels). Tem de utilizar Secure Sockets Layer (SSL) para todos os URLs.
"groups": [ { "id": "msgReadGroup", "label": "Contoso Add-in", "icons": [ { "size": 16, "url": "https://localhost:3000/assets/icon-16.png" }, { "size": 32, "url": "https://localhost:3000/assets/icon-32.png" }, { "size": 80, "url": "https://localhost:3000/assets/icon-80.png" } ], "controls": [ { // properties omitted } ] } ]- O
Certifique-se de que existe um objeto de controlo na
"controls"matriz. Apresentamos um exemplo a seguir. Tenha em atenção o seguinte sobre este JSON:- As
"id"propriedades ,"label"e"icons"têm a mesma finalidade e as mesmas restrições que as propriedades correspondentes de um objeto de grupo, exceto que se aplicam ao menu pendente dentro do grupo. - A
"type"propriedade está definida para"menu"o que significa que o controlo será um menu pendente. - O
"supertip.title"(comprimento máximo: 64 carateres) e"supertip.description"(comprimento máximo: 128 carateres) aparecem quando o cursor está a pairar sobre o menu. - A
"items"propriedade contém o JSON para as duas opções de menu. Os valores são adicionados em passos posteriores.
{ "id": "msgReadMenu", "type": "menu", "label": "Contoso Menu", "icons": [ { "size": 16, "url": "https://localhost:3000/assets/icon-16.png" }, { "size": 32, "url": "https://localhost:3000/assets/icon-32.png" }, { "size": 80, "url": "https://localhost:3000/assets/icon-80.png" } ], "supertip": { "title": "Show Contoso Actions", "description": "Opens the Contoso menu." }, "items": [ { "id": "", "type": "", "label": "", "supertip": {}, "actionId": "" }, { "id": "", "type": "", "label": "", "supertip": {}, "actionId": "" } ] }- As
O primeiro item mostra um painel de tarefas. Apresentamos um exemplo a seguir. Observe o seguinte sobre este código:
- As
"id"propriedades ,"label"e"supertip"têm a mesma finalidade e as mesmas restrições que as propriedades correspondentes do objeto de menu principal, exceto que se aplicam apenas a esta opção de menu. - A
"icons"propriedade é opcional para itens de menu e não existe nenhuma neste exemplo. Se incluir um, tem as mesmas finalidades e restrições que a"icons"propriedade do menu principal, exceto que o ícone aparece no item de menu junto à etiqueta. - A propriedade
"type"está definida como"menuItem". - O
"actionId"tem de ser uma correspondência exata para o"runtimes.actions.id"que definiu em Configurar o runtime para o comando do painel de tarefas.
{ "id": "msgReadOpenPaneMenuItem", "type": "menuItem", "label": "Show Task Pane", "supertip": { "title": "Show Contoso Task Pane", "description": "Opens the Contoso task pane." }, "actionId": "ShowTaskPane" },- As
O segundo item executa um comando de função. Apresentamos um exemplo a seguir. Observe o seguinte sobre este código:
- O
"actionId"tem de ser uma correspondência exata para o"runtimes.actions.id"que definiu em Configurar o runtime para o comando da função.
{ "id": "msgReadSetNotificationMenuItem", "type": "menuItem", "label": "Set Notification", "supertip": { "title": "Set Notification", "description": "Displays a notification message on the current message." }, "actionId": "SetNotification" }- O
Concluiu a adição de um menu ao seu suplemento. Faça sideload e teste-o.