Especificación de aplicaciones de Office y requisitos de API con el manifiesto unificado

El complemento de Office puede depender de una aplicación de Office específica (también denominada host de Office) o de miembros específicos de la Biblioteca de JavaScript de Office (office.js). Por ejemplo, el complemento podría:

• Ejecutarse en una sola aplicación de Office (por ejemplo, Word o Excel), o en varias aplicaciones.
• Use las API de JavaScript de Office que solo están disponibles en algunas versiones de Office. Por ejemplo, la versión perpetua con licencia por volumen de Excel 2016 no admite todas las API relacionadas con Excel en la biblioteca de JavaScript de Office.
• Estar diseñado para su uso solo en un factor de forma móvil.

En estas situaciones, debe asegurarse de que el complemento nunca esté instalado en aplicaciones de Office o versiones de Office en las que no se pueda ejecutar.

También hay escenarios en los que desea controlar qué características del complemento son visibles para los usuarios en función de su aplicación de Office y su versión de Office. Tres ejemplos son:

• El complemento tiene características que son útiles tanto en Word como en PowerPoint, como la manipulación de texto, pero tiene algunas características adicionales que solo tienen sentido en PowerPoint, como las características de administración de diapositivas. Debe ocultar las características solo de PowerPoint cuando el complemento se ejecuta en Word.
• El complemento tiene una característica que requiere un método de API de JavaScript de Office que se admite en algunas versiones de una aplicación de Office, como excel de suscripción de Microsoft 365, pero no se admite en otros, como Excel 2016 perpetuas con licencia por volumen. Pero el complemento tiene otras características que solo requieren métodos de API de JavaScript de Office que se admiten en Excel 2016 perpetuas con licencia por volumen. En este escenario, necesita que el complemento se pueda instalar en esa versión de Excel 2016, pero la característica que requiere el método no admitido debe estar oculta a esos usuarios.
• El complemento tiene características que se admiten en Office de escritorio, pero no en Office móvil.

Este artículo le ayuda a comprender cómo asegurarse de que el complemento funciona según lo esperado y llega a la audiencia más amplia posible.

Uso de la biblioteca de API de JavaScript de Office más reciente

El complemento debe cargar la versión más reciente de la biblioteca de API de JavaScript de Office desde la red de entrega de contenido (CDN). Para ello, asegúrese de que tiene la siguiente <script> etiqueta en el primer archivo HTML que se abre el complemento. El uso de /1/ en la dirección URL de la red CDN garantiza que se haga referencia a la versión más reciente de Office.js.

<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>

Especificar qué aplicaciones de Office pueden hospedar el complemento

Para especificar las aplicaciones de Office en las que se puede instalar el complemento, use la "extensions.requirements.scopes" matriz . Especifique cualquier subconjunto de "mail", "workbook", "document"y "presentation". En la tabla siguiente se muestra qué combinaciones de plataforma y aplicación de Office corresponden a estos valores. También se muestra qué tipo de complemento se puede instalar para cada ámbito.

Por ejemplo, el siguiente JSON especifica que el complemento puede instalarse en cualquier versión de Excel, que incluye Excel en la Web, Windows e iPad, pero no se puede instalar en ninguna otra aplicación de Office.

"extensions": [
    {
        "requirements": {
            "scopes": [ "workbook" ],
        },
        ...
    }
]

Especificar qué API de Office necesita el complemento

No se pueden especificar explícitamente las versiones y compilaciones de Office ni las plataformas en las que se debe instalar el complemento, y no lo haría porque tendría que revisar el manifiesto siempre que se admitan las características de complemento que el complemento usa para ampliarse a una nueva versión o plataforma. En su lugar, especifique en el manifiesto las API que necesita el complemento. Office impide que el complemento se instale en combinaciones de versión y plataforma de Office que no admiten las API y garantiza que el complemento no aparecerá en Mis complementos.

Conjuntos de requisitos

Para simplificar el proceso de especificar las API que necesita el complemento, Office agrupa la mayoría de las API en conjuntos de requisitos. Las API del modelo de objetos de Common API se agrupan por la característica de desarrollo que admiten. Por ejemplo, todas las API conectadas a enlaces de tabla se encuentran en el conjunto de requisitos denominado "TableBindings 1.1". Las API de los modelos de objetos específicos de la aplicación se agrupan por cuando se publicaron para su uso en complementos de producción.

Los conjuntos de requisitos tienen versiones. Por ejemplo, las API que admiten cuadros de diálogo se encuentran en el conjunto de requisitos DialogApi 1.1. Cuando se lanzaron api adicionales que habilitan la mensajería desde un panel de tareas a un cuadro de diálogo, se agruparon en DialogApi 1.2, junto con todas las API de DialogApi 1.1. Cada versión de un conjunto de requisitos es un superconjunto de todas las versiones anteriores.

La compatibilidad del conjunto de requisitos varía según la aplicación de Office, la versión de la aplicación de Office y la plataforma en la que se ejecuta. Por ejemplo, ExcelApi 1.17 no se admite en versiones perpetuas con licencia por volumen de Office antes de Office 2024, pero ExcelApi 1.14 se admite de nuevo en Office 2021. Quiere que el complemento se pueda instalar en cada combinación de plataforma y versión de Office que admita las API que usa, por lo que siempre debe especificar en el manifiesto la versión mínima de cada conjunto de requisitos que requiere el complemento. Los detalles sobre cómo hacerlo se detallan más adelante en este artículo.

Propiedad extensions.requirements.capabilities

Use la "requirements.capabilities" propiedad para especificar los conjuntos de requisitos mínimos que debe admitir la aplicación de Office para instalar el complemento. Si la aplicación o plataforma de Office no admite los conjuntos de requisitos o los miembros de la API especificados en la "requirements.capabilities" propiedad , el complemento no se ejecutará en esa aplicación o plataforma y no se mostrará en Mis complementos.

En el ejemplo de código siguiente se muestra cómo configurar un complemento que se puede instalar en todas las combinaciones de aplicaciones y plataformas de Office que admiten lo siguiente:

• TableBindings conjunto de requisitos, que tiene una versión mínima de "1.1".
• OOXML conjunto de requisitos, que tiene una versión mínima de "1.1".

"extensions": [
    {
        "requirements": {
            "capabilities": [ 
                {
                    "name": "TableBindings",
                    "minVersion": "1.1"
                },
                {
                    "name": "OOXML",
                    "minVersion": "1.1"
                }
            ],
        },
        ...
    }
]

Especificar los factores de forma en los que se puede instalar el complemento

Para un complemento de Outlook, puede especificar si el complemento se debe instalar en el escritorio (incluye tabletas) o factores de forma móviles. Para configurar esto, use la "extensions.requirements.formFactors" propiedad . En el ejemplo siguiente se muestra cómo hacer que el complemento de Outlook sea instalable en ambos factores de forma.

"extensions": [
    {
        "requirements": {
            ...
            "formFactors": [
                "desktop",
                "mobile"
            ]
        },
        ...
    }
]

Diseño para experiencias alternativas

Las características de extensibilidad que proporciona la plataforma de complementos de Office se pueden dividir útilmente en tres tipos:

• Características de extensibilidad que están disponibles inmediatamente después de instalar el complemento. Un ejemplo de este tipo de característica es Comandos de complemento, que son botones y menús personalizados de la cinta de opciones.
• Características de extensibilidad que solo están disponibles cuando se ejecuta el complemento y que se implementan con Office.js API de JavaScript; por ejemplo, cuadros de diálogo.
• Características de extensibilidad que solo están disponibles en tiempo de ejecución, pero que se implementan con una combinación de Office.js configuración de JavaScript y manifiesto. Algunos ejemplos son las funciones personalizadas de Excel, el inicio de sesión único y las pestañas contextuales personalizadas.

Si el complemento usa una característica de extensibilidad específica para algunas de sus funciones, pero tiene otras funciones útiles que no requieren la característica de extensibilidad, debe diseñar el complemento para que se pueda instalar en las combinaciones de plataforma y versión de Office que no admiten la característica de extensibilidad. Puede proporcionar una experiencia valiosa, aunque disminuida, en esas combinaciones.

Este diseño se implementa de forma diferente en función de cómo se implemente la característica de extensibilidad:

• Para conocer las características implementadas completamente con JavaScript, consulte Comprobación de la disponibilidad de api en tiempo de ejecución.
• Para conocer las características que requieren que configure el manifiesto, consulte la sección "Filtrar características" de Especificar requisitos de complementos de Office en el manifiesto unificado para Microsoft 365.

Vea también

• Manifiesto de complementos de Office
• Conjuntos de requisitos de complementos de Office
• Especificar los requisitos de complementos de Office en el manifiesto unificado para Microsoft 365