Complementos de Office con el manifiesto de aplicación unificada para Microsoft 365
En este artículo se presenta el manifiesto de aplicación unificada para Microsoft 365. Se supone que está familiarizado con el manifiesto de complementos de Office.
Sugerencia
- Para obtener información general sobre el manifiesto de solo complemento, vea Complementos de Office con el manifiesto de solo complemento.
- Si está familiarizado con el manifiesto de solo complemento, es posible que obtenga más información sobre el manifiesto unificado con formato JSON leyendo Comparar el manifiesto de solo complemento con el manifiesto unificado para Microsoft 365.
Microsoft está realizando una serie de mejoras en la plataforma para desarrolladores de Microsoft 365. Estas mejoras proporcionan más coherencia en el desarrollo, la implementación, la instalación y la administración de todos los tipos de extensiones de Microsoft 365, incluidos los complementos de Office. Estos cambios son compatibles con los complementos existentes.
Una mejora importante es la capacidad de crear una sola unidad de distribución para todas las extensiones de Microsoft 365 mediante el mismo formato de manifiesto y esquema.
Hemos dado un primer paso importante hacia estos objetivos al hacer posible crear complementos de Outlook con un manifiesto unificado para Microsoft 365.
Nota:
- El manifiesto unificado actualmente solo admite complementos de Outlook y solo en Office vinculado a una suscripción de Microsoft 365 e instalado en Windows, en un dispositivo móvil o en Outlook en la Web. Estamos trabajando en ampliar la compatibilidad con Excel, PowerPoint y Word, así como con Outlook en Mac y con versiones perpetuas de Office.
- El manifiesto unificado requiere office versión 2304 (compilación 16320.00000) o posterior.
Sugerencia
¿Listo para empezar a trabajar con el manifiesto unificado? Comience por Compilar un complemento de Outlook con el manifiesto unificado para Microsoft 365.
Propiedades clave del manifiesto unificado
La documentación de referencia principal para la versión del manifiesto de aplicación unificada se encuentra en Referencia de manifiesto unificado. (Para obtener la referencia de manifiesto que incluye todas las características de versión preliminar más recientes, consulte Versión preliminar del desarrollador público para el manifiesto unificado). En este artículo, se proporciona una breve descripción del significado de las propiedades base cuando la aplicación de Teams es (o incluye) un complemento de Office. Esto va seguido de alguna documentación básica para la propiedad "extensiones" y sus propiedades descendientes. Hay un manifiesto de ejemplo completo para un complemento en Manifiesto unificado de ejemplo.
Propiedades base
Cada una de las propiedades base enumeradas en la tabla siguiente tiene documentación más amplia en El esquema de manifiesto. Las propiedades base no incluidas en esta tabla no tienen ningún significado para los complementos de Office.
| Propiedad JSON | Objetivo |
|---|---|
| “$schema” | Identifica el esquema del manifiesto. |
| “manifestVersion” | Versión del esquema del manifiesto. |
| “id” | GUID de la aplicación o complemento de Teams. |
| “version” | Versión de la aplicación o complemento de Teams. El formato debe ser n.n.n donde cada uno de ellos n no puede tener más de cinco dígitos. |
| “name” | Nombres cortos y largos públicos de la aplicación o complemento de Teams. El nombre corto aparece en la parte superior del panel de tareas de un complemento. |
| “description” | Descripciones cortas y largas públicas de la aplicación o complemento de Teams. |
| "developer" | Información sobre el desarrollador de la aplicación o complemento de Teams. |
| “localizationInfo” | Configura la configuración regional predeterminada y otras configuraciones regionales admitidas. |
| "validDomains" | Consulte Especificar dominios seguros. |
| “webApplicationInfo” | Identifica la aplicación web de la aplicación o complemento de Teams como se conoce en Azure Active Directory. |
| “authorization” | Identifica los permisos de Microsoft Graph que necesita el complemento. |
Propiedad "extensiones"
Estamos trabajando duro para completar la documentación de referencia de la propiedad "extensiones" y sus propiedades descendientes. Mientras tanto, a continuación se proporciona documentación básica. La mayoría de las propiedades, pero no todas, tienen un elemento (o atributo) equivalente en el manifiesto de solo complemento para los complementos. En su mayor parte, la descripción y las restricciones que se aplican al elemento o atributo XML también se aplican a su propiedad JSON equivalente en el manifiesto unificado. Las tablas de la sección "extensiones" (propiedad) de Compare the add-in only manifest with the unified manifest for Microsoft 365 (Comparar el manifiesto de solo complemento con el manifiesto unificado de Microsoft 365 ) pueden ayudarle a determinar el equivalente XML de una propiedad JSON.
Nota:
Esta tabla contiene solo algunas propiedades descendientes representativas seleccionadas de "extensiones". No es una lista exhaustiva de todas las propiedades secundarias de "extensiones". Para obtener la referencia completa del manifiesto unificado, consulte Manifiesto unificado para Microsoft 365. Para obtener la referencia de manifiesto que incluye todas las características de versión preliminar más recientes, consulte Versión preliminar del desarrollador público para el manifiesto unificado para Microsoft 365.
| Propiedad JSON | Objetivo |
|---|---|
| “requirements.capabilities” | Identifica los conjuntos de requisitos que debe instalar el complemento. |
| “requirements.scopes” | Identifica las aplicaciones Office en las que se puede instalar el complemento. Por ejemplo, "mail" significa que el complemento se puede instalar en Outlook. |
| “cintas de opciones” | Las cintas de opciones que personaliza el complemento. |
| "ribbons.contexts" | Especifica las superficies de comandos que personaliza el complemento. Por ejemplo, "mailRead" o "mailCompose". |
| "ribbons.fixedControls" (versión preliminar para desarrolladores) | Configura y agrega el botón de un complemento integrado de informes de correo no deseado a la cinta de opciones de Outlook. |
| "ribbons.spamPreProcessingDialog" (versión preliminar para desarrolladores) | Configura el cuadro de diálogo de preprocesamiento que se muestra después de seleccionar el botón de un complemento de informes de correo no deseado en la cinta de opciones de Outlook. |
| "ribbons.tabs" | Configura pestañas personalizadas de la cinta de opciones. |
| "alternativas" | Especifica la compatibilidad con versiones anteriores con un complemento COM equivalente, XLL o ambos. También especifica los iconos principales que se usan para representar el complemento en versiones anteriores de Office. |
| “runtimes” | Configura los tiempos de ejecución incrustados que usa el complemento, incluidos varios tipos de complementos que tienen poca o ninguna interfaz de usuario, como complementos personalizados de solo función y comandos de función. |
| “autoRunEvents” | Este punto de extensión agrega un controlador de eventos para un evento especificado. |
Especificar dominios seguros
Hay una matriz "validDomains" en el archivo de manifiesto que se usa para indicar a Office a qué dominios debe poder navegar el complemento. Como se indica en Especificar dominios que desea abrir en la ventana del complemento, al ejecutarse en Office en la Web, el panel de tareas se puede navegar a cualquier dirección URL. Sin embargo, en las plataformas de escritorio, si el complemento intenta ir a una dirección URL de un dominio distinto del dominio que hospeda la página de inicio, esa dirección URL se abre en una nueva ventana del explorador fuera del panel de complementos de la aplicación de Office.
Para invalidar este comportamiento en las plataformas de escritorio, agregue cada dominio que quiera abrir en la ventana del complemento a la lista de dominios especificados en la matriz "validDomains". Si el complemento intenta ir a una dirección URL en un dominio que está en la lista, se abrirá en el panel de tareas de Office de escritorio y Office en la web. Si intenta ir a una dirección URL que no está en la lista, en Office en el escritorio, esa dirección URL se abre en una nueva ventana del explorador (fuera del panel de tareas del complemento).
Manifiesto unificado de ejemplo
A continuación se muestra un ejemplo de un manifiesto de aplicación unificada para un complemento. No contiene todas las propiedades de manifiesto posibles.
{
"$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
"id": "00000000-0000-0000-0000-000000000000",
"version": "1.0.0",
"manifestVersion": "devPreview",
"name": {
"short": "Name of your app (<=30 chars)",
"full": "Full name of app, if longer than 30 characters (<=100 chars)"
},
"description": {
"short": "Short description of your app (<= 80 chars)",
"full": "Full description of your app (<= 4000 chars)"
},
"icons": {
"outline": "outline.png",
"color": "color.png"
},
"accentColor": "#230201",
"developer": {
"name": "Contoso",
"websiteUrl": "https://www.contoso.com",
"privacyUrl": "https://www.contoso.com/privacy",
"termsOfUseUrl": "https://www.contoso.com/servicesagreement"
},
"localizationInfo": {
"defaultLanguageTag": "en-us",
"additionalLanguages": [
{
"languageTag": "es-es",
"file": "es-es.json"
}
]
},
"webApplicationInfo": {
"id": "00000000-0000-0000-0000-000000000000",
"resource": "api://www.contoso.com/prodapp"
},
"authorization": {
"permissions": {
"resourceSpecific": [
{
"name": "Mailbox.ReadWrite.User",
"type": "Delegated"
}
]
}
},
"extensions": [
{
"requirements": {
"scopes": [ "mail" ],
"capabilities": [
{
"name": "Mailbox", "minVersion": "1.1"
}
]
},
"runtimes": [
{
"requirements": {
"capabilities": [
{
"name": "MailBox",
"minVersion": "1.10"
}
]
},
"id": "eventsRuntime",
"type": "general",
"code": {
"page": "https://contoso.com/events.html",
"script": "https://contoso.com/events.js"
},
"lifetime": "short",
"actions": [
{
"id": "onMessageSending",
"type": "executeFunction"
},
{
"id": "onNewMessageComposeCreated",
"type": "executeFunction"
}
]
},
{
"requirements": {
"capabilities": [
{
"name": "MailBox", "minVersion": "1.1"
}
]
},
"id": "commandsRuntime",
"type": "general",
"code": {
"page": "https://contoso.com/commands.html",
"script": "https://contoso.com/commands.js"
},
"lifetime": "short",
"actions": [
{
"id": "action1",
"type": "executeFunction"
},
{
"id": "action2",
"type": "executeFunction"
},
{
"id": "action3",
"type": "executeFunction"
}
]
}
],
"ribbons": [
{
"contexts": [
"mailCompose"
],
"tabs": [
{
"builtInTabId": "TabDefault",
"groups": [
{
"id": "dashboard",
"label": "Controls",
"controls": [
{
"id": "control1",
"type": "button",
"label": "Action 1",
"icons": [
{
"size": 16,
"url": "test_16.png"
},
{
"size": 32,
"url": "test_32.png"
},
{
"size": 80,
"url": "test_80.png"
}
],
"supertip": {
"title": "Action 1 Title",
"description": "Action 1 Description"
},
"actionId": "action1"
},
{
"id": "menu1",
"type": "menu",
"label": "My Menu",
"icons": [
{
"size": 16,
"url": "test_16.png"
},
{
"size": 32,
"url": "test_32.png"
},
{
"size": 80,
"url": "test_80.png"
}
],
"supertip": {
"title": "My Menu",
"description": "Menu with 2 actions"
},
"items": [
{
"id": "menuItem1",
"type": "menuItem",
"label": "Action 2",
"supertip": {
"title": "Action 2 Title",
"description": "Action 2 Description"
},
"actionId": "action2"
},
{
"id": "menuItem2",
"type": "menuItem",
"label": "Action 3",
"icons": [
{
"size": 16,
"url": "test_16.png"
},
{
"size": 32,
"url": "test_32.png"
},
{
"size": 80,
"url": "test_80.png"
}
],
"supertip": {
"title": "Action 3 Title",
"description": "Action 3 Description"
},
"actionId": "action3"
}
]
}
]
}
],
}
]
},
{
"contexts": [ "mailRead" ],
"tabs": [
{
"builtInTabId": "TabDefault",
"groups": [
{
"id": "dashboard",
"label": "Controls",
"controls": [
{
"id": "control1",
"type": "button",
"label": "Action 1",
"icons": [
{
"size": 16,
"url": "test_16.png"
},
{
"size": 32,
"url": "test_32.png"
},
{
"size": 80,
"url": "test_80.png"
}
],
"supertip": {
"title": "Action 1 Title",
"description": "Action 1 Description"
},
"actionId": "action1"
}
]
}
],
"customMobileRibbonGroups" [
{
"id": "myMobileGroup",
"label": "Contoso Actions",
"controls": [
{
"id": "msgReadFunctionButton",
"type": "mobileButton",
"label": "Action 1",
"icons": [
{
"size": 16,
"url": "test_16.png"
},
{
"size": 32,
"url": "test_32.png"
},
{
"size": 80,
"url": "test_80.png"
}
],
"supertip": {
"title": "Action 1 Title",
"description": "Action 1 Description"
},
"actionId": "action1"
}
]
}
]
"customMobileRibbonGroups": [
{
"id": "mobileDashboard",
"label": "Controls",
"controls": [
{
"id": "control1",
"type": "mobileButton",
"label": "Action 1",
"icons": [
{
"size": 16,
"url": "test_16.png"
},
{
"size": 32,
"url": "test_32.png"
},
{
"size": 80,
"url": "test_80.png"
}
],
"supertip": {
"title": "Action 1 Title",
"description": "Action 1 Description"
},
"actionId": "action1"
}
]
}
]
}
]
}
],
"autoRunEvents": [
{
"requirements": {
"capabilities": [
{
"name": "MailBox", "minVersion": "1.10"
}
]
},
"events": [
{
"type": "newMessageComposeCreated",
"actionId": "onNewMessageComposeCreated"
},
{
"type": "messageSending",
"actionId": "onMessageSending",
"options": {
"sendMode": "promptUser"
}
}
]
}
],
"alternates": [
{
"requirements": {
"scopes": [ "mail" ]
},
"prefer": {
"comAddin": {
"progId": "ContosoExtension"
}
},
"hide": {
"storeOfficeAddin": {
"officeAddinId": "00000000-0000-0000-0000-000000000000",
"assetId": "WA000000000"
}
},
"alternateIcons": {
"icon": {
"size": 64,
"url": "https://contoso.com/assets/icon64x64.jpg"
},
"highResolutionIcon": {
"size": 64,
"url": "https://contoso.com/assets/icon128x128.jpg"
}
}
}
]
}
]
}