Especificar las aplicaciones de Office y los requisitos de API con el manifiesto de solo complemento

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:

• Ejecutar 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 de licencia por volumen de Excel 2016 no admite todas las API relacionadas con Excel en la biblioteca JavaScript de Office.

En estas situaciones, debe asegurarse de que el complemento nunca se instala en aplicaciones o versiones de Office en las que no se puede 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 y versión de Office. A continuación se pueden ver dos ejemplos:

• 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 exclusivas 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 es compatible con algunas versiones de una aplicación de Office, como Excel de suscripción a Microsoft 365, pero no lo es en otras, como Excel 2016 perpetuo con licencia por volumen. Pero el complemento tiene otras características que solo requieren métodos de API de JavaScript de Office compatibles con Excel 2016 perpetuo 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 ocultarse a esos usuarios.

Este artículo ayuda a comprender las opciones que se tienen que elegir para asegurarse de que el complemento funciona según lo esperado y de que llega al público más amplio posible.

Usar la biblioteca de API 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 etiqueta siguiente <script> en el primer archivo HTML que abra 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://officeapis.public.onecdn.static.microsoft/1/office.js" type="text/javascript"></script>

Especificar qué aplicaciones de Office pueden hospedar el complemento

De forma predeterminada, un complemento se puede instalar en todas las aplicaciones de Office compatibles con el tipo de complemento especificado (es decir, Correo, Panel de tareas o Contenido). Por ejemplo, un complemento del panel de tareas se puede instalar de forma predeterminada en Access, Excel, OneNote, PowerPoint, Project y Word.

Para asegurarse de que el complemento solo se puede instalar en un subconjunto de aplicaciones de Office, use los elementos Hosts y Host del manifiesto de solo complemento.

Por ejemplo, la declaración siguiente <Hosts> especifica <Host> que el complemento se puede instalar en cualquier versión de Excel, lo que incluye Excel en la Web, Windows y iPad, pero no se puede instalar en ninguna otra aplicación de Office.

<Hosts>
  <Host Name="Workbook" />
</Hosts>

El <Hosts> elemento puede contener uno o varios <Host> elementos. Debe haber un elemento independiente <Host> para cada aplicación de Office en la que se pueda instalar el complemento. El Name atributo es obligatorio y se puede establecer en uno de los siguientes valores.

Especifique qué versiones y plataformas de Office pueden hospedar el complemento

No puede especificar explícitamente las versiones y compilaciones de Office o las plataformas en las que se debe instalar el complemento, y no lo desearía porque tendría que revisar su manifiesto cada vez que la compatibilidad con las características del complemento que usa el complemento se amplíe 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 API común se agrupan por la característica de desarrollo que admiten. Por ejemplo, todas las API conectadas a los 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 cuándo se publicaron para su uso en complementos de producción.

Los conjuntos de requisitos están versionados. 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 permiten la mensajería de 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 con los conjuntos 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 nuevamente en Office 2021. Desea que el complemento se pueda instalar en todas las combinaciones de plataforma y versión de Office que admitan 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. Más adelante en este artículo se ofrece información detallada sobre cómo hacerlo.

Elemento Requirements

Use el elemento Requirements y sus conjuntos de elementos secundarios para especificar los conjuntos de requisitos mínimos que debe admitir la aplicación de Office para instalar el complemento.

Todas las API en los modelos específicos de la aplicación están en conjuntos de requisitos, pero algunas de las del modelo de API común no lo están. Use los métodos para especificar los miembros de API sin conjunto que requiere el complemento. No puede usar el <Methods> elemento con complementos de Outlook.

Si la plataforma o la aplicación de Office no admiten los conjuntos de requisitos o los miembros de API especificados en el <Requirements> elemento, 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 aplicaciones de Office que admiten lo siguiente:

• TableBindings conjunto de requisitos, que tiene una versión mínima de "1.1".
• OoxmlCoercion conjunto de requisitos, que tiene una versión mínima de "1.1".
• Document.getSelectedDataAsync método.

<OfficeApp ... >
  ...
  <Requirements>
     <Sets DefaultMinVersion="1.1">
        <Set Name="TableBindings" MinVersion="1.1"/>
        <Set Name="OoxmlCoercion" MinVersion="1.1"/>
     </Sets>
     <Methods>
        <Method Name="Document.getSelectedDataAsync"/>
     </Methods>
  </Requirements>
    ...
</OfficeApp>

Tenga en cuenta lo siguiente sobre este ejemplo.

• El <Requirements> elemento contiene los <Sets> elementos and <Methods> secundarios.
• El <Sets> elemento puede contener uno o varios <Set> elementos. DefaultMinVersion Especifica el valor predeterminado MinVersion de todos los elementos secundarios <Set> .
• Un elemento Establecer especifica un conjunto de requisitos que la aplicación de Office debe admitir para que el complemento se pueda instalar. El Name atributo especifica el nombre del conjunto de requisitos. Especifica MinVersion la versión mínima del conjunto de requisitos. MinVersion Reemplaza el valor del DefaultMinVersion atributo en el elemento primario <Sets>.
• El <Methods> elemento puede contener uno o varios elementos de método . No puede usar el <Methods> elemento con complementos de Outlook.
• El <Method> elemento especifica un método individual que la aplicación de Office debe admitir para que el complemento se pueda instalar. El Name atributo es obligatorio y especifica el nombre del método calificado con su objeto padre.

Diseño para experiencias alternativas

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

• Características de extensibilidad que están disponibles inmediatamente después de instalar el complemento. Puede usar este tipo de característica configurando un elemento VersionOverrides en el manifiesto. Un ejemplo de este tipo de característica son los 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 JavaScript y configuración en un <VersionOverrides> elemento. 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 funcionalidades útiles que no requieren la característica de extensibilidad, debe diseñar el complemento para que se pueda instalar en combinaciones de plataformas y versiones de Office que no admitan 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 ver las características implementadas completamente con JavaScript, consulte Comprobar la disponibilidad de la API en tiempo de ejecución.
• Para las funciones que requieren que configure un <VersionOverrides> elemento, consulte Especificación de requisitos en un elemento VersionOverrides.

Especificar requisitos en un elemento VersionOverrides

El elemento VersionOverrides se agregó al esquema de manifiesto principalmente, pero no exclusivamente, para admitir características que deben estar disponibles inmediatamente después de instalar un complemento, como los comandos de complemento (botones y menús personalizados de la cinta de opciones). Office debe conocer estas características cuando analice el manifiesto del complemento.

Supongamos que el complemento usa una de estas características, pero es valioso y se debería poder instalar, incluso en versiones de Office que no lo admitan. En esta situación, identifique la característica mediante un elemento Requirements (y sus elementos secundarios Sets y Methods ) que incluya como elemento secundario del <VersionOverrides> propio elemento en lugar de como elemento secundario del elemento base OfficeApp . El efecto de hacer esto es que Office permitirá que se instale el complemento, pero Office omitirá algunos de los elementos secundarios del elemento en las versiones de Office en las <VersionOverrides> que no se admita la característica.

Específicamente, se omiten los elementos secundarios que <VersionOverrides> anulan elementos del manifiesto base, como un <Hosts> elemento, y se usan en su lugar los elementos correspondientes del manifiesto base. Sin embargo, puede haber elementos secundarios en un <VersionOverrides> que realmente implementen características adicionales en lugar de invalidar la configuración en el manifiesto base. Dos ejemplos son el WebApplicationInfo y .EquivalentAddins Estas partes no <VersionOverrides>se omitirán, suponiendo que la plataforma y la versión de Office admitan la característica correspondiente.

Para obtener información sobre los elementos descendientes del <Requirements> elemento, consulte Requirements element anteriormente en este artículo.

A continuación se muestra un ejemplo.

<VersionOverrides ... >
   ...
   <Requirements>
      <Sets DefaultMinVersion="1.1">
         <Set Name="WordApi" MinVersion="1.2"/>
      </Sets>
   </Requirements>
   <Hosts>

      <!-- ALL MARKUP INSIDE THE HOSTS ELEMENT IS IGNORED WHEREVER WordApi 1.2 IS NOT SUPPORTED -->

      <Host xsi:type="Workbook">
         <!-- markup for custom add-in commands -->
      </Host>
   </Hosts>
</VersionOverrides>

Vea también

• Manifiesto de complementos de Office
• Conjuntos de requisitos de complementos de Office
• Ejemplos de complementos de Office