Entenda como personalizar Suplementos do Office
A plataforma de Suplementos do Office permite que você personalize seu suplemento. Neste módulo, você explorará como personalizar seu suplemento através da persistência do estado, e usando Fluent UI e Microsoft Graph. Ao final deste módulo, você deve saber como personalizar os suplementos de Office usando estado persistente, IU Fluent Design, e Microsoft Graph.
Entender as opções para manter o estado e as configurações
A plataforma Suplementos Office fornece várias maneiras para que seu suplemento persista no estado e nas configurações. Suas opções dependem dos aplicativos do Office que você planeja dar suporte e do tipo de suplemento que planeja desenvolver.
Opções para persistir no estado e nas configurações
A API JavaScript do Office fornece objetos para seu suplemento salvar o estado nas sessões do usuário. A tabela a seguir lista as opções, juntamente com os tipos de suplementos com suporte e os aplicativos de host do Office.
| Objeto de API do Office | Tipos de suplemento com suporte | Hosts do Office com suporte | Informações de armazenamento |
|---|---|---|---|
| CustomProperties | MailApp | Outlook | Os dados do item são armazenados na mensagem ou no compromisso em que o suplemento está funcionando. |
| CustomXmlParts | TaskPaneApp | Excel (API JavaScript do Excel específica do host), Word (API Comum JavaScript do Office) |
Os dados são armazenados em uma parte XML personalizada do documento ou da pasta de trabalho. |
| RoamingSettings | MailApp | Outlook | Os dados são armazenados na caixa de correio do Exchange do usuário e associados ao suplemento específico. |
| Configurações | ContentApp, TaskPaneApp | Excel, PowerPoint, Word | Os dados são armazenados no documento, na pasta de trabalho ou na apresentação em que o suplemento está funcionando. |
*Dados armazenados em pares de nome/valor em um recipiente de propriedades
Você também pode usar o armazenamento da Web em HTML5 e outras técnicas disponíveis através do controle do navegador subjacente do suplemento.
Importante
Não armazene senhas e PII (informações de identificação pessoal) confidenciais no dispositivo do usuário.
Entenda a IU Fluent Design em Suplementos Office
Ao criar seu suplemento, você tem muitos fatores de projeto de IU a considerar. A IU Fluent Design fornece elementos que aderem à marca Office para que seu suplemento pareça uma extensão natural do Office.
Observação
Usar o UI Fabric é opcional, mas recomendado.
Sobre a Fluent UI
A IU fluente tem duas (2) áreas principais:
- Fabric Core – Fornece elementos básicos como fonte, ícones e cor
- Componentes do Fabric React – Inclui elementos do Fabric Core e adiciona entrada, navegação, componentes de notificação, entre outros
Fabric Core
O Fabric Core fornece elementos de design básicos que refletem ou sincronizam com a identidade visual do Office.
Para começar a usar o Fabric Core, faça referência ao CSS na sua página HTML, conforme mostrado no código a seguir.
<link rel="stylesheet" href="https://static2.sharepointonline.com/files/fabric/office-ui-fabric-core/9.6.1/css/fabric.min.css">
Em seguida, você pode usar ícones, fontes e cores do Fabric. O exemplo a seguir mostra como incluir um ícone de tabela extra-grande na cor do tema principal do aplicativo do Office.
<i class="ms-Icon ms-font-xl ms-Icon--Table ms-fontColor-themePrimary"></i>
Componentes do Fabric
O Fabric React fornece componentes UX para entrada, navegação, notificação e outras categorias. Ele se baseia e inclui o Fabric Core.
Os componentes recomendados que você pode usar no seu suplemento são os seguinte:
- Trilha
- Botão
- Caixa de seleção
- ChoiceGroup
- Lista suspensa
- Rótulo
- Listar
- Dinamizar
- Campo de texto
- Alternância
Dica
Você pode usar o gerador Yeoman para suplementos Office para criar um projeto que faça referência à Fabric React. Um tipo de projeto disponível é Projeto do Painel de Tarefas do Suplemento do Office usando a estrutura React.
Entenda quando e como usar o Microsoft Graph in Suplementos Office
Seu suplemento pode se conectar ao Microsoft Graph e acessar os dados do usuário para que ele possa alcançar cenários mais úteis e produtivos. As tarefas de exemplo são:
- Ler arquivos do OneDrive
- Buscar anexos de email
- Obter o perfil do usuário
Por que usar o Microsoft Graph
As APIs REST do Microsoft Graph fornecem uma maneira de seu suplemento acessar os dados do usuário em serviços como:
- Microsoft Entra ID
- Serviços do Microsoft 365
- Serviços do Enterprise Mobility and Security
- Serviços do Windows 10
- Dynamics 365
Como autorizar o Microsoft Graph
Para se conectar e usar o Microsoft Graph, o seu suplemento precisa:
- Autenticar o usuário
- Estar autorizado a agir em nome do usuário
Autenticação
O suplemento pode obter um token de acesso a partir do ID do Microsoft Entra quando o utilizador tiver sessão iniciada. O ID do Microsoft Entra não permite que a respetiva página de início de sessão seja aberta num iframe e o painel de tarefas do suplemento é um iframe quando o suplemento é iniciado no Office na Web. Por isso, utilize a API de Caixa de Diálogo JavaScript do Office para apresentar o formulário de início de sessão do Microsoft Entra. Se seu suplemento inclui funções personalizadas que precisam de autorização para o Microsoft Graph, use as funções personalizadas da API de Caixa de Diálogo para exibir o formulário de entrada.
Autorização
Após o usuário entrar, seu suplemento obtém um token de acesso para usar em chamadas de API posteriores ao Microsoft Graph. O token de acesso nunca pode dar ao suplemento mais ou maiores permissões do que o usuário tem. Geralmente, os usuários só têm permissões para seus próprios dados, arquivos e emails, e objetos que foram compartilhados com eles. Se seu suplemento obtiver dados do Microsoft Graph de outros usuários, então ele só pode ser usado com êxito por usuários com permissões de nível de administrador.
Bibliotecas recomendadas
Dependendo das suas opções de desenvolvimento, você pode usar uma das seguintes bibliotecas para autenticação e autorização, dependendo do caso.
- Seu lado do servidor está em uma estrutura com base em .NET (por exemplo, .NET Core ou ASP.NET): use MSAL.NET
- O lado do servidor é baseado em node.js: utilizar o Passport Microsoft Entra ID
- O seu suplemento usa o fluxo Implícito: use msal.js
Resumo
A plataforma de suplementos Office permite que você personalize seu suplemento. Neste módulo, você explorou como personalizar seu suplemento através da persistência do estado, e usando Fluent UI e Microsoft Graph. Ao final deste módulo, você deve saber como personalizar os suplementos de Office usando estado persistente, IU Fluent Design, e Microsoft Graph.