Información sobre cómo personalizar Complementos de Office
La plataforma Complementos de Office le permite personalizar el complemento. En este módulo, aprenderá a personalizar su complemento mediante un estado persistente utilizando Fluent UI y Microsoft Graph. Al final de este módulo, debería saber cómo personalizar Complementos de Office mediante un estado persistente, Fluent UI y Microsoft Graph.
Comprender las opciones de estado y configuración persistentes
La plataforma Complementos de Office ofrece varias formas para que persistan el estado y la configuración del complemento. Las opciones dependen de las aplicaciones de Office que planee admitir y del tipo de complemento que planee desarrollar.
Opciones de persistencia de estado y configuración
La API de JavaScript de Office proporciona objetos para que el complemento guarde el estado en las distintas sesiones de usuario. En la tabla siguiente se muestran las opciones, junto con los tipos de complementos compatibles y las aplicaciones host de Office
| Objeto de API de Office | Tipos de complementos admitidos | Hosts de Office admitidos | Información de almacenamiento |
|---|---|---|---|
| CustomProperties | MailApp | Outlook | Los datos de elementos se almacenan en el mensaje o cita en el que está trabajando el complemento.* |
| CustomXmlParts | TaskPaneApp | Excel (API de JavaScript de Excel específica del host), Word (API común de JavaScript de Office) |
Los datos se almacenan en una parte XML personalizada del documento o libro. |
| RoamingSettings | MailApp | Outlook | Los datos se almacenan en el buzón de Exchange del usuario y se asocian al complemento específico.* |
| Configuración | ContentApp, TaskPaneApp | Excel, PowerPoint y Word | Los datos se almacenan en el documento, libro o presentación en el que está trabajando el complemento.* |
* Datos almacenados en pares de nombre/valor en un contenedor de propiedades
También puede usar el almacenamiento web HTML5 y otras técnicas disponibles a través del control de explorador subyacente del complemento.
Importante
No almacene contraseñas ni información confidencial de identificación personal (PII) en el dispositivo del usuario.
Descripción de la interfaz de usuario de Fluent UI en Complementos de Office
A medida que cree su complemento, tendrá muchos factores de diseño de la interfaz de usuario que debe considerar. Fluent UI proporciona elementos que se ajustan a la personalización de marca de Office, por lo que su complemento tiene el aspecto de una extensión natural de Office.
Nota:
Si bien es opcional, se recomienda usar Fluent UI.
Acerca de Fluent UI
Fluent UI de Office tiene dos (2) áreas principales:
- Fabric Core: proporciona elementos básicos como la fuente, los iconos y el color
- Componentes de Fabric React: incluye los elementos de Fabric Core y agrega componentes de entrada, navegación y notificación, entre otros
Fabric Core
Fabric Core proporciona elementos de diseño básicos que reflejan la personalización de marca de Office o se sincronizan con ella.
Para empezar a usar Fabric Core, haga referencia al CSS en su página HTML, como se muestra en el código siguiente.
<link rel="stylesheet" href="https://static2.sharepointonline.com/files/fabric/office-ui-fabric-core/9.6.1/css/fabric.min.css">
Después puede usar los iconos, las fuentes y los colores de los iconos de Fabric. En el ejemplo siguiente se muestra cómo puede incluir un icono de tabla extra grande en el color de tema principal de la aplicación de Office.
<i class="ms-Icon ms-font-xl ms-Icon--Table ms-fontColor-themePrimary"></i>
Componentes de Fabric
Fabric React ofrece componentes de experiencia de usuario para entradas, navegación, notificación y otras categorías. Se basa en Fabric Core y lo incluye.
Los componentes recomendados que puede usar en el complemento son los siguientes:
- Ruta de navegación
- Botón
- Casilla
- ChoiceGroup
- Desplegable
- Etiqueta
- Lista
- Documento principal
- Campo de texto
- Alternancia
Sugerencia
Use el generador de Yeoman para Complementos de Office para crear un proyecto que haga referencia a Fabric React. Un tipo de proyecto disponible es Proyecto del panel de tareas del complemento de Office con el marco de React.
Comprender cuándo y cómo usar Microsoft Graph en Complementos de Office
Su complemento puede conectarse a Microsoft Graph y obtener acceso a los datos del usuario para lograr escenarios más útiles y productivos. Estas son algunas de las tareas de ejemplo:
- Leer archivos desde OneDrive
- Recuperar datos adjuntos de correo electrónico
- Obtener el perfil del usuario
¿Por qué debería usar Microsoft Graph?
Las API de REST de Microsoft Graph proporcionan a su complemento una forma de obtener acceso a los datos del usuario en servicios como:
- Microsoft Entra ID
- Servicios de Microsoft 365
- Servicios de Enterprise Mobility + Security.
- Servicios de Windows 10
- Dynamics 365
Cómo autorizar a Microsoft Graph
Para conectarse a Microsoft Graph y usarlo, su complemento debe:
- Autentificar el usuario
- Estar autorizado para actuar en nombre del usuario
Autenticación
El complemento puede obtener un token de acceso de Microsoft Entra ID cuando el usuario ha iniciado sesión. Microsoft Entra ID no permite que su página de inicio de sesión se abra en un iframe y el panel de tareas del complemento es un iframe cuando el complemento se inicia en Office en la Web. Por lo tanto, use la API de diálogo de JavaScript de Office para mostrar el formulario de inicio de sesión de Microsoft Entra. Si el complemento incluye funciones personalizadas que necesitan autorización para Microsoft Graph, use la API del cuadro de diálogo de funciones personalizadas para mostrar el formulario de inicio de sesión.
Autorización
Cuando el usuario inicia sesión, el complemento recibe un token de acceso para usar en las llamadas de API a Microsoft Graph posteriores. El token de acceso nunca puede dar al complemento más permisos o permisos superiores a los que tiene el usuario. Normalmente, los usuarios solo tienen permisos para obtener datos sobre sí mismos, sus propios archivos, correo electrónico y objetos que se han compartido con ellos. Si el complemento obtiene datos de Microsoft Graph sobre varios usuarios, entonces solo los usuarios con permisos de administrador pueden usarlos correctamente.
Bibliotecas recomendadas
Según las opciones de desarrollo, puede usar una de las siguientes bibliotecas para la autenticación y autorización, según corresponda.
- El lado del servidor se encuentra en un marco basado en .NET (por ejemplo, .NET Core o ASP.NET): use MSAL.NET
- El lado servidor está basado en node.js: use Passport Microsoft Entra ID
- El complemento usa flujo implícito, use msal. js
Resumen
La plataforma Complementos de Office le permite personalizar el complemento. En este módulo, aprendió a personalizar el complemento mediante un estado persistente utilizando Fluent UI y Microsoft Graph. Al final de este módulo, debería saber cómo personalizar Complementos de Office mediante un estado persistente, Fluent UI y Microsoft Graph.