Comprobación de la disponibilidad de la API en tiempo de ejecución
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.
Cuando la diferencia en las dos experiencias consta por completo de diferencias en las API de la biblioteca de JavaScript de Office a las que se llama y no en ninguna característica configurada en el manifiesto, se prueba en tiempo de ejecución para detectar si el cliente de Office del usuario admite un conjunto de requisitos de API. También puede probar en tiempo de ejecución si se admiten las API que no están en un conjunto.
Nota:
Para proporcionar experiencias alternativas con características que requieren configuración de manifiesto, siga las instrucciones de Especificar hosts de Office y requisitos de API con el manifiesto unificado o Especificar aplicaciones de Office y requisitos de API con el manifiesto de solo complemento.
Comprobación de la compatibilidad con conjuntos de requisitos
El método isSetSupported se usa para comprobar si hay compatibilidad con conjuntos de requisitos. 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.
// For example, 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
ifinstrucció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.
Comprobación de la compatibilidad con api sin configuración
Cuando el complemento depende de un método que no forma parte de un conjunto de requisitos, denominado API sin conjunto, use una 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`.
}