Entenda os fundamentos dos suplementos do Office
A plataforma de Suplementos do Office permite estender a funcionalidade dos aplicativos do Office. Neste módulo, você explorará várias maneiras de usar suplementos para estender e interagir com os aplicativos do Office. Você também aprenderá sobre como configurar seu suplemento usando o arquivo de manifesto do suplemento.
Entenda o painel de tarefas e os complementos de conteúdo
Os Suplementos do Office oferecem várias opções de como sua solução pode interagir com um aplicativo do Office. Nesta unidade, discutiremos duas destas opções:
- Painel de tarefas
- Conteúdo
Suplementos do painel de tarefas
Os suplementos do painel de tarefas permitem a interação do usuário por meio de um painel exibido em um aplicativo do Office. Com a interface do painel de tarefas, você pode permitir que o usuário modifique documentos ou e-mails, veja dados de uma fonte de dados e muito mais. Na imagem a seguir, o painel de tarefas é o painel exibido à direita do documento.
Complemento do painel de tarefas exibido em um aplicativo do Office
Em versões mais recentes do Word, do Excel e do PowerPoint, você pode configurar o painel de tarefas para ser exibido automaticamente quando um usuário abrir um arquivo. O usuário precisará ter o seu complemento instalado primeiro para ativar esse comportamento.
Definir o tipo de complemento do painel de tarefas
Conforme descrito anteriormente, o arquivo de manifesto de um complemento define as configurações e os recursos do complemento.
Para configurar um complemento como um complemento do painel de tarefas para qualquer aplicativo do Office, exceto o Outlook, defina o atributo xsi:type como TaskPaneApp dentro do elemento OfficeApp do arquivo de manifesto, conforme mostrado no exemplo a seguir.
<OfficeApp
...
xsi:type="TaskPaneApp">
...
</OfficeApp>
Para configurar um complemento para o Outlook, defina o atributo xsi:type como MailApp no elemento OfficeApp do arquivo de manifesto, conforme mostrado no exemplo a seguir.
<OfficeApp
...
xsi:type="MailApp">
...
</OfficeApp>
Suplementos de conteúdo
Os suplementos de conteúdo podem ser usados para inserir um objeto em uma planilha do Excel ou apresentação do PowerPoint. Esse objeto pode ser uma visualização de dados baseada na Web, mídia ou outro conteúdo externo. Na imagem a seguir, o complemento de conteúdo é exibido próximo ao centro do documento.
Complemento de conteúdo carregado em um aplicativo do Office
Definir o tipo de complemento de conteúdo
Conforme descrito anteriormente, o arquivo de manifesto de um complemento define as configurações e os recursos do complemento. Para configurar um add-in como um complemento de conteúdo, defina o atributo xsi:type como ContentApp dentro do elemento OfficeApp do arquivo de manifesto, conforme mostrado no exemplo a seguir.
<OfficeApp
...
xsi:type="ContentApp">
...
</OfficeApp>
Entenda as caixas de diálogo de Suplementos do Office
A plataforma de Suplementos do Office permite exibir uma caixa de diálogo para os usuários:
- Entre em um serviço integrado (por exemplo, autenticar com a Conta Microsoft, Google ou Facebook).
- Confirme a ação do usuário.
- Execute uma tarefa que pode estar muito restrita em um painel de tarefas (por exemplo, exibir um vídeo).
A janela da caixa de diálogo não é modal, o que significa que o usuário pode continuar a interagir com o aplicativo do Office e com o seu complemento enquanto a janela da caixa de diálogo é exibida. A imagem a seguir mostra uma caixa de diálogo sendo exibida em um aplicativo do Office.
Caixa de diálogo exibida em um aplicativo do Office
Entenda as funções personalizadas dos Suplementos do Office
Os Suplementos do Office permitem que você crie funções personalizadas de JavaScript ou TypeScript que podem ser acessadas como funções do Excel criadas como SUM().
A imagem a seguir mostra uma função personalizada chamada SPHEREVOLUME sendo inserida no Excel.
Função personalizada sendo inserida no Excel
O exemplo de código a seguir mostra o código JavaScript para a função SPHEREVOLUME() mostrado anteriormente.
/**
* Returns the volume of a sphere.
* @customfunction
* @param {number} radius
*/
function sphereVolume(radius) {
return (Math.pow(radius, 3) * 4 * Math.PI) / 3;
}
Onde você pode usar funções personalizadas?
As funções personalizadas estão disponíveis no Excel nas seguintes plataformas.
- Windows (conectado a uma assinatura do Microsoft 365)
- macOS (conectado a uma assinatura do Microsoft 365)
- Navegador da Web
Definir o tipo de complemento de função personalizado
Para configurar um complemento para conter funções personalizadas, as configurações de teclas no manifesto são as seguinte para os complementos do Excel.
<OfficeApp
...
xsi:type="TaskPaneApp">
...
<Hosts>
<Host Name="Workbook"/>
</Hosts>
...
<VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
<Hosts>
<Host xsi:type="Workbook">
<AllFormFactors>
<ExtensionPoint xsi:type="CustomFunctions">
...
</ExtensionPoint>
</AllFormFactors>
</Host>
</Hosts>
...
</VersionOverrides>
</OfficeApp>
Entenda os comandos do complemento
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.
Comandos do complemento no Excel, Word, PowerPoint e OneNote
Você pode configurar um complemento para que um usuário possa executar o mesmo selecionando:
- Faixa de opções do aplicativo do Office ou botão de menu de estouro de comando
- Configuração do manifesto principal:
<ExtensionPoint xsi:type="PrimaryCommandSurface">.
- Configuração do manifesto principal:
- Item de menu de contexto
- Configuração do manifesto principal:
<ExtensionPoint xsi:type="ContextMenu">.
- Configuração do manifesto principal:
Um comando de complemento também pode abrir um submenu com mais comandos.
Observação
Atualmente os suplementos de conteúdo não dão suporte a comandos de suplemento.
A imagem a seguir mostra três comandos de complemento (botões personalizados) adicionados à guia Dadosda faixa de opções do Excel.
Comandos de complemento no Excel no Windows
Comandos de complemento no Outlook
Você pode configurar um complemento para que um usuário possa execute-o selecionando um botão na faixa de opções do Office ou no menu de estouro de comando quando o usuário estiver:
- Ler uma mensagem no painel de leitura ou em uma janela pop-out.
- Configuração do manifesto principal:
<ExtensionPoint xsi:type="MessageReadCommandSurface">.
- Configuração do manifesto principal:
- Redigir uma mensagem.
- Configuração do manifesto principal:
<ExtensionPoint xsi:type="MessageComposeCommandSurface">.
- Configuração do manifesto principal:
- Criar ou exibir um compromisso ou uma reunião como organizador.
- Configuração do manifesto principal:
<ExtensionPoint xsi:type="AppointmentOrganizerCommandSurface">.
- Configuração do manifesto principal:
- Exibir uma reunião como participante.
- Configuração do manifesto principal:
<ExtensionPoint xsi:type="AppointmentAttendeeCommandSurface">.
- Configuração do manifesto principal:
Um comando de complemento também pode abrir um submenu com mais comandos.
As imagens a seguir mostram três comandos de complemento (botões personalizados) adicionados à faixa de opções do Outlook. Na primeira imagem, os botões são renderizados em um estado regular; na segunda imagem, os botões são renderizados em um estado recolhido.
Comandos de complemento no Outlook no Windows
Onde você pode usar os comandos do complemento?
Os comandos do complemento estão disponíveis no Excel, Outlook, OneNote, PowerPoint e Word, conforme mostrado na tabela a seguir.
| Plataforma | Versão principal do Office | Assinatura ou compra única? | Observações |
|---|---|---|---|
| Windows | Não aplicável | conectado à assinatura do Microsoft 365 | Não disponível no OneNote |
| 2021 | compra única | Não disponível no OneNote | |
| 2019 | compra única | Não disponível no OneNote | |
| 2016 | compra única | Disponível apenas no Outlook no Exchange 2016 (requer atualização pós-lançamento) ou posterior. Não disponível em outros aplicativos do Office. | |
| 2013 | compra única | Disponível apenas no Outlook no Exchange 2016 ou posterior. Requer atualizações pós-lançamento para o Outlook e o Exchange 2016. Não disponível em outros aplicativos do Office. | |
| macOS | Não aplicável | conectado à assinatura do Microsoft 365 | Não disponível no OneNote |
| 2021 | compra única | Não disponível no OneNote | |
| 2019 | compra única | Não disponível no OneNote | |
| 2016 | compra única | Não disponível no OneNote | |
| iOS | Não aplicável | conectado à assinatura do Microsoft 365 | Somente Disponível no Outlook |
| Android | Não aplicável | conectado à assinatura do Microsoft 365 | Somente Disponível no Outlook |
| navegador da Web | Não aplicável | Não aplicável | Disponível em todos os aplicativos do Office com suporte |
Entenda a finalidade do manifesto do complemento
O arquivo de manifesto XML de um suplemento do Office define as configurações e as funcionalidades do suplemento. Você pode configurá-lo para controlar como o seu complemento é renderizado e se comporta nos aplicativos do Office direcionados.
O que o manifesto define
No manifesto, você define as informações importantes sobre o complemento, incluindo:
- Metadados de complemento (por exemplo, ID, versão, descrição, nome de exibição, localidade padrão)
- Informações sobre como o complemento se integra ao Office (por exemplo, aplicativos de destino, funcionalidade personalizada, comandos do complemento)
- Localização de imagens que o suplemento usa para identidade visual e iconografia de comando.
- Permissões necessárias para o suplemento.
- Dimensões do suplemento (por exemplo, dimensões para suplementos de conteúdo, altura solicitada para suplementos do Outlook).
- Regras que especificam quando o complemento deve ser ativado em uma mensagem ou compromisso (somente Outlook)
Como o manifesto é usado
Um manifesto de complemento é usado das seguintes maneiras:
- Os aplicativos do Office em que o seu complemento é executado usam informações do manifesto para renderizar a interface do usuário do complemento e transferir botões personalizados ou entradas de menu.
- Se você publicar seu complemento na AppSource:
- As informações do manifesto (nome, descrição, autor, logotipo e assim por diante) são usadas para criar a entrada do aplicativo que é exibida para possíveis clientes no AppSource.
- O processo de validação de AppSource lê as informações do manifesto e valida que o seu complemento é executado nas plataformas esperadas.
Resumo
A plataforma de Suplementos do Office permite estender a funcionalidade dos aplicativos do Office. Neste módulo, você explorou várias maneiras de usar suplementos para estender e interagir com os aplicativos do Office. Você também aprendeu sobre como configurar seu suplemento usando o arquivo de manifesto do suplemento.