Compartir a través de

Especificar las aplicaciones de Office y los requisitos de la API

  • Artículo

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 API 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.

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. Dos 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 perpetuo 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 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 estar oculta 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.

Nota:

Para obtener una vista de alto nivel de dónde se admiten actualmente los complementos de Office, consulte la página Disponibilidad de la plataforma y la aplicación cliente de Office para complementos de Office .

Sugerencia

Muchas de las tareas descritas en este artículo se realizan automáticamente, en su totalidad o en parte, al crear el proyecto de complemento con una herramienta, como el generador de Yeoman para complementos de Office o una de las plantillas de complementos de Office en Visual Studio. En tales casos, interprete la tarea como un significado que debe comprobar que se ha realizado.

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.1/hosted/office.js" type="text/javascript"></script>

Especificar qué aplicaciones de Office pueden hospedar el complemento

De forma predeterminada, se puede instalar un complemento 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 de panel de tareas se puede instalar de forma predeterminada en Access, Excel, OneNote, PowerPoint, Project y Word.

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

Por ejemplo, la siguiente <declaración Hosts> y <Host> especifica que el complemento puede instalarse 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 <elemento Hosts> puede contener uno o varios <elementos Host> . Debe haber un elemento Host> independiente< para cada aplicación de Office en la que se debe instalar el complemento. El Name atributo es obligatorio y se puede establecer en uno de los siguientes valores.

Nombre Aplicaciones cliente de Office Tipos de complemento disponibles
Documento Word en la web, Windows, Mac, iPad Panel de tareas
Mailbox Outlook en la web, Windows (nuevo y clásico), Mac, Android, iOS Correo
Bloc de notas OneNote en la web Panel de tareas, Contenido
Presentación PowerPoint en la web, Windows, Mac, iPad Panel de tareas, Contenido
Project Project en Windows Panel de tareas
Libro de trabajo Excel en la web, Windows, Mac, iPad Panel de tareas, Contenido
Base de datos Acceso (obsoleto) Panel de tareas

Nota:

Las aplicaciones de Office se admiten en diferentes plataformas y se ejecutan en escritorios, exploradores web, tabletas y dispositivos móviles. Normalmente no se puede especificar qué plataforma se puede usar para ejecutar el complemento. Por ejemplo, si especifica Workbook, tanto Excel en la web como en Windows se pueden usar para ejecutar el complemento. Sin embargo, si especifica Mailbox, el complemento no se ejecutará en clientes móviles de Outlook a menos que defina el punto de extensión móvil.

Nota:

No es posible que un manifiesto de complemento se aplique a más de un tipo: Correo, Panel de tareas o Contenido. Esto significa que si desea que el complemento se pueda instalar en Outlook y en una de las otras aplicaciones de Office, debe crear dos complementos, uno con un manifiesto de tipo Mail y el otro con un panel Tarea o un manifiesto de tipo de contenido.

Especificar qué versiones y plataformas de Office pueden hospedar 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.

Importante

Use solo el manifiesto base para especificar los miembros de la API que el complemento debe tener para ser de cualquier valor significativo. Si el complemento usa una API para algunas características, pero tiene otras características útiles que no requieren la API, debe diseñar el complemento para que se pueda instalar en la plataforma y en las combinaciones de versiones de Office que no admiten la API, pero que proporcionan una experiencia disminuida en esas combinaciones. Para obtener más información, vea Diseño para experiencias alternativas.

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, DialogApi 1.2 no se admite en las versiones perpetuas con licencia por volumen de Office antes de Office 2021, pero DialogApi 1.1 se admite en todas las versiones perpetuas de vuelta a Office 2016. 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.

Sugerencia

Para obtener más información sobre el control de versiones del conjunto de requisitos, vea Disponibilidad de conjuntos de requisitos de Office y para obtener listas completas de conjuntos de requisitos e información sobre las API de cada una, comience con conjuntos de requisitos de complementos de Office. Los temas de referencia de la mayoría de las API de Office.js también especifican el conjunto de requisitos al que pertenecen (si existe).

Nota:

Algunos conjuntos de requisitos también tienen elementos de manifiesto asociados a ellos. Consulte Especificación de requisitos en un elemento VersionOverrides para obtener información sobre cuándo este hecho es relevante para el diseño del complemento.

API que no están en un conjunto de requisitos

Todas las API de 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. También hay una manera de especificar una de estas API sin conjunto en el manifiesto cuando el complemento requiere una. Puede ver información más detallada en este mismo artículo más adelante.

Elemento Requirements

Use el elemento Requirements y sus elementos secundarios Sets y Methods para especificar los conjuntos de requisitos mínimos o los miembros de la API 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 el <elemento Requirements> , el complemento no se ejecutará en esa aplicación o plataforma y no se mostrará en Mis complementos.

Nota:

El <elemento Requirements> es opcional para todos los complementos, excepto para los complementos de Outlook. Cuando el xsi:type atributo del elemento raíz OfficeApp es MailApp, debe haber un <elemento Requirements> que especifique la versión mínima del conjunto de requisitos mailbox que requiere el complemento. Para obtener más información, vea Conjuntos de requisitos de la API de JavaScript de Outlook.

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".
  • OOXML 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="OOXML" MinVersion="1.1"/>
     </Sets>
     <Methods>
        <Method Name="Document.getSelectedDataAsync"/>
     </Methods>
  </Requirements>
    ...
</OfficeApp>

Tenga en cuenta lo siguiente sobre este ejemplo.

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

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. Puede usar este tipo de característica configurando un elemento VersionOverrides en el manifiesto. 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 JavaScript y configuración en un <elemento VersionOverrides> . 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:

El tiempo de ejecución comprueba si hay compatibilidad con el método y el conjunto de requisitos

Pruebe en tiempo de ejecución para detectar si office del usuario admite un conjunto de requisitos con el método isSetSupported . Pase el nombre del conjunto de requisitos y la versión mínima como parámetros. Si se admite el conjunto de requisitos, isSetSupported devuelve true. El código siguiente muestra un ejemplo.

if (Office.context.requirements.isSetSupported('WordApi', '1.2'))
{
   // Code that uses API members from the WordApi 1.2 requirement set.
} else {
   // Provide diminished experience here. E.g., run alternate code when the user's Word is volume-licensed perpetual Word 2016 (which doesn't support WordApi 1.2).
}

Sobre este código, tenga en cuenta:

  • Se requiere el primer parámetro. Es una cadena que representa el nombre del conjunto de requisitos. Para obtener más información sobre los conjuntos de requisitos disponibles, vea Conjuntos de requisitos de complementos de Office.
  • El segundo parámetro es opcional. Se trata de una cadena que especifica la versión mínima del conjunto de requisitos que la aplicación de Office debe admitir para que se ejecute el código de la if instrucción (por ejemplo, "1.9"). Si no se usa, se supone la versión "1.1".

Advertencia

Al llamar al isSetSupported método , el valor del segundo parámetro (si se especifica) debe ser una cadena no un número. El analizador de JavaScript no puede diferenciar entre valores numéricos como 1.1 y 1.10, mientras que puede para valores de cadena como "1.1" y "1.10".

En la tabla siguiente se muestran los nombres del conjunto de requisitos para los modelos de API específicos de la aplicación.

Aplicación de Office RequirementSetName
Excel ExcelApi
OneNote OneNoteApi
Outlook Buzón de correo
PowerPoint PowerPointApi
Word WordApi

A continuación se muestra un ejemplo de uso del método con uno de los conjuntos de requisitos del modelo de API común.

if (Office.context.requirements.isSetSupported('CustomXmlParts'))
{
    // Run code that uses API members from the CustomXmlParts requirement set.
}
else
{
    // Run alternate code when the user's Office application doesn't support the CustomXmlParts requirement set.
}

Nota:

El isSetSupported método y los conjuntos de requisitos de estas aplicaciones están disponibles en el archivo de Office.js más reciente en la red CDN. Si no usa Office.js de la red CDN, el complemento podría generar excepciones si usa una versión anterior de la biblioteca en la que isSetSupported no está definido. Para obtener más información, consulte Uso de la biblioteca de API de JavaScript de Office más reciente.

Cuando el complemento depende de un método que no forma parte de un conjunto de requisitos, use la comprobación en tiempo de ejecución para determinar si la aplicación de Office admite el método, como se muestra en el ejemplo de código siguiente. Para obtener una lista completa de los métodos que no pertenecen a un conjunto de requisitos, consulte Conjuntos de requisitos de complementos de Office.

Nota:

Se recomienda limitar el uso de este tipo de comprobación en tiempo de ejecución en el código de complemento.

En el ejemplo de código siguiente se comprueba si la aplicación de Office admite document.setSelectedDataAsync.

if (Office.context.document.setSelectedDataAsync)
{
    // Run code that uses `document.setSelectedDataAsync`.
}

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 comandos de complemento (botones y menús personalizados de la cinta de opciones). Office debe conocer estas características cuando analiza el manifiesto del complemento.

Supongamos que el complemento usa una de estas características, pero el complemento es valioso y debe ser instalable, incluso en las versiones de Office que no admiten la característica. En este escenario, identifique la característica mediante un elemento Requirements (y sus elementos Sets y Methods secundarios) que incluya como elemento secundario del <propio elemento VersionOverrides> en lugar de como elemento secundario del elemento base OfficeApp . El efecto de hacerlo es que Office permitirá instalar el complemento, pero Office omitirá algunos de los elementos secundarios del< elemento VersionOverrides> en las versiones de Office donde no se admite la característica.

En concreto, los elementos secundarios de VersionOverrides<> que invalidan elementos del manifiesto base, como un <elemento Hosts>, se omiten y se usan los elementos correspondientes del manifiesto base en su lugar. Sin embargo, puede haber elementos secundarios en una <versionOverrides> que realmente implementan características adicionales en lugar de invalidar la configuración en el manifiesto base. Dos ejemplos son y WebApplicationInfoEquivalentAddins. Estas partes de VersionOverrides<>no se omitirán, suponiendo que la plataforma y la versión de Office admiten la característica correspondiente.

Para obtener información sobre los elementos descendientes del <elemento Requirements> , vea Requirements element earlier in this article.

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>

Advertencia

Tenga mucho cuidado antes de incluir un <elemento Requirements> en versionOverrides<>, ya que en las combinaciones de plataforma y versión que no admiten el requisito, no se instalará ninguno de los comandos del complemento, incluso los que invocan la funcionalidad que no necesita el requisito. Considere, por ejemplo, un complemento que tiene dos botones de cinta personalizados. Una de ellas llama a las API de JavaScript de Office que están disponibles en el conjunto de requisitos ExcelApi 1.4 (y versiones posteriores). El resto llama a las API que solo están disponibles en ExcelApi 1.9 (y versiones posteriores). Si pone un requisito para ExcelApi 1.9 en VersionOverrides<, cuando no se admite 1.9, ninguno de los botones> aparecerá en la cinta de opciones. Una mejor estrategia en este escenario sería usar la técnica descrita en Comprobaciones en tiempo de ejecución para la compatibilidad con el método y el conjunto de requisitos. El código invocado por el segundo botón usa isSetSupported primero para comprobar la compatibilidad con ExcelApi 1.9. Si no se admite, el código proporciona al usuario un mensaje que indica que esta característica del complemento no está disponible en su versión de Office.

Sugerencia

No tiene sentido repetir un elemento Requirement en una <versionOverrides> que ya aparece en el manifiesto base. Si el requisito se especifica en el manifiesto base, el complemento no se puede instalar cuando no se admite el requisito, por lo que Office ni siquiera analiza el <elemento VersionOverrides> .

Vea también