Compatibilidad con versiones anteriores de Microsoft WebView y Office
Los complementos de Office son aplicaciones web que se muestran dentro de iframes cuando se ejecutan en Office en la web. Los complementos de Office se muestran mediante un control de explorador incrustado (también conocido como vista web) cuando se ejecutan en Office en Windows u Office en Mac. El sistema operativo o un explorador instalado en el equipo del usuario proporcionan los controles del explorador incrustados.
Importante
Las vistas web de Internet Explorer y Microsoft Edge heredado todavía se usan en complementos de Office
Algunas combinaciones de plataformas y versiones de Office, incluidas las versiones perpetuas con licencia por volumen a través de Office 2019, siguen usando los controles de vista web que vienen con Internet Explorer 11 (denominado "Trident") y Microsoft Edge Legacy (denominado "EdgeHTML") para hospedar complementos, como se explica en Exploradores y controles de vista web usados por complementos de Office. Internet Explorer 11 se deshabilitó en Windows 10 y Windows 11 en febrero de 2023, y se quitó la interfaz de usuario para iniciarla; pero todavía está instalado en con esos sistemas operativos. Por lo tanto, Office todavía puede llamar a Trident y otras funciones de Internet Explorer mediante programación.
Se recomienda (pero no es necesario) que admita estas combinaciones, al menos de forma mínima, proporcionando a los usuarios del complemento un mensaje de error correcto cuando el complemento se inicie en estas vistas web. Tenga en cuenta estos puntos adicionales:
- Office en la web ya no se abre en Internet Explorer o Microsoft Edge Heredado. Por lo tanto, AppSource no prueba los complementos en Office en la web en estos exploradores.
- AppSource sigue realizando pruebas para las combinaciones de versiones de escritorio de Office y plataforma que usan Trident o EdgeHTML. Sin embargo, solo emite una advertencia cuando el complemento no admite estas vistas web; AppSource no rechaza el complemento.
- La herramienta Script Lab ya no admite Trident.
Si tiene previsto admitir versiones anteriores de Windows y Office, el complemento debe funcionar en los controles de explorador incrustables que usan estas versiones. Por ejemplo, controles de explorador basados en Internet Explorer 11 (IE11) o Microsoft Edge Heredado (basado en EdgeHTML). Para obtener información sobre qué combinaciones de Windows y Office usan estos controles de explorador, vea Exploradores y controles de vista web que usan los complementos de Office.
Determinación de la vista web en la que se ejecuta el complemento en tiempo de ejecución
El complemento puede detectar la vista web en la que se ejecuta leyendo la propiedad window.navigator.userAgent . Esto permite que el complemento proporcione una experiencia alternativa o que se produzca un error correctamente. A continuación se muestra un ejemplo que determina si el complemento se ejecuta en Trident o EdgeHTML.
if (navigator.userAgent.indexOf("Trident") !== -1) {
/*
Trident is the webview in use. Do one of the following:
1. Provide an alternate add-in experience that doesn't use any of the HTML5
features that aren't supported in Trident (Internet Explorer 11).
2. Enable the add-in to gracefully fail by adding a message to the UI that
says something similar to:
"This add-in won't run in your version of Office. Please upgrade either to
perpetual Office 2021 (or later) or to a Microsoft 365 account."
*/
} else if (navigator.userAgent.indexOf("Edge") !== -1) {
/*
EdgeHTML is the browser in use. Do one of the following:
1. Provide an alternate add-in experience that's supported in EdgeHTML (Microsoft Edge Legacy).
2. Enable the add-in to gracefully fail by adding a message to the UI that
says something similar to:
"This add-in won't run in your version of Office. Please upgrade either to
perpetual Office 2021 (or later) or to a Microsoft 365 account."
*/
} else {
/*
A webview other than Trident or EdgeHTML is in use.
Provide a full-featured version of the add-in here.
*/
}
Nota:
Microsoft Edge (Chromium) devuelve edg/ seguido de uno o más dígitos de versión y cero o más . separadores como agente de usuario; por ejemplo, edg/76.0.167.1. Tenga en cuenta que no e está presente al final del nombre. Es "edg", no "edge".
Este JavaScript debe estar lo más pronto posible en el proceso de inicio del complemento. A continuación se muestra un ejemplo de una página principal del complemento que aconseja a los usuarios que actualicen Office cuando se detecte Trident.
<!doctype html>
<html lang="en" data-framework="typescript">
<head>
<meta charset="UTF-8" />
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Contoso Task Pane Add-in</title>
<!-- Office JavaScript API -->
<script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js"></script>
</head>
<body>
<div id="main">
<!--
The add-in UI is here.
-->
</div>
<!--
The script below makes the following div display if the
webview is Trident, and hides the regular div.
-->
<div id="tridentmessage" style="display: none; padding: 10;">
This add-in will not run in your version of Office. Please upgrade either to
perpetual Office 2021 (or later) or to a Microsoft 365 account.
</div>
<script>
if (navigator.userAgent.indexOf("Trident") !== -1) {
var tridentMessage = document.getElementById("tridentmessage");
var normalUI = document.getElementById("main");
tridentMessage.style.display = "block";
normalUI.style.display = "none";
}
</script>
</body>
</html>
Importante
No siempre es una buena práctica leer la userAgent propiedad. Asegúrese de que está familiarizado con el artículo Detección de exploradores mediante el agente de usuario, incluidas las recomendaciones y alternativas para leer userAgent. En concreto, si proporciona una experiencia de complemento alternativa para admitir el uso de Trident, considere la posibilidad de usar la detección de características en lugar de realizar pruebas para el agente de usuario. Pero si solo proporciona una notificación de que el complemento no funciona en Trident, como en este caso, el uso userAgent es adecuado.
A partir del 24 de julio de 2023, las versiones no inglesas del artículo están obsoletas en distintos grados; algunos tienen más de 12 años de antigüedad.
A partir de la misma fecha, el texto y las tablas de la sección ¿Qué parte del agente de usuario contiene la información que está buscando? de la versión en inglés del artículo ya no mencionan Trident o Internet Explorer 11. En la tabla nombre del explorador y versión, la fila de Internet Explorer 11 era la siguiente:
| Motor | Debe contener | No debe contener |
|---|---|---|
| Internet Explorer 11 | Trident/7.0; .*rv:xyz |
En la tabla del motor de representación, la fila de Trident era la siguiente:
| Motor | Debe contener | Comentario |
|---|---|---|
| Tridente | Trident/xyz |
Internet Explorer coloca este fragmento en la sección de comentarios de la cadena de User-Agent. |
Revisión de la información de compatibilidad con la versión de Office y webview
Para obtener más información sobre cómo admitir vistas web específicas y versiones de Office, seleccione la pestaña correspondiente.
El motor de JavaScript asociado a Trident no admite versiones de JavaScript posteriores a ES5. Para usar versiones más modernas de JavaScript o para usar TypeScript, consulte Compatibilidad con versiones recientes de JavaScript.
Importante
Trident no admite algunas características HTML5, como medios, grabación y ubicación. Si el complemento debe admitir Trident, debe diseñar el complemento para evitar estas características no admitidas o el complemento debe detectar cuándo se usa Trident y proporcionar una experiencia alternativa que no use las características no admitidas. Para obtener más información, vea Determinar la vista web en la que se ejecuta el complemento en tiempo de ejecución.
Prueba de un complemento en Trident (Internet Explorer)
Consulte Pruebas de Trident.
Compatibilidad con versiones recientes de JavaScript
Si desea usar la sintaxis y las características de una versión de JavaScript más reciente que la que se admite en la vista web o el entorno de ejecución en el que se ejecuta el código, o si desea usar TypeScript, debe usar un transpilador, un polyfill o ambos. Por ejemplo, un transpilador convertirá la sintaxis o los operadores, como el => operador , que es desconocido en ES5, en ES5. Un polyfill reemplaza los métodos, los tipos y las clases de una versión más reciente de JavaScript en una funcionalidad equivalente en una versión anterior.
En las subsecciones siguientes se supone que el estándar de JavaScript de destino es ES5, pero la información también se aplica a otros destinos. Por ejemplo, si el destino es ECMAScript 2016, reemplace "ES5" por "ECMAScript 2016" (y "post-ES5" por "post-ECMAScript 2016") en estas subsecciones.
Uso de un transpilador
Puede escribir el código en TypeScript o JavaScript moderno y, a continuación, transpilándolo en tiempo de compilación en ES5 JavaScript. Los archivos ES5 resultantes son los que se cargan en la aplicación web del complemento.
Hay dos transpiladores populares. Ambos pueden trabajar con archivos de origen que son TypeScript o JavaScript posterior a ES5. También funcionan con archivos react (.jsx y .tsx).
Consulte la documentación de cualquiera de ellos para obtener información sobre cómo instalar y configurar el transpilador en el proyecto de complemento. Se recomienda usar un ejecutor de tareas, como Grunt o WebPack , para automatizar la transpilación. Para obtener un complemento de ejemplo que usa tsc, vea Complemento de Office Microsoft Graph React. Para obtener un ejemplo que usa babel, consulte Complemento de almacenamiento sin conexión.
Nota:
Si usa Visual Studio (no Visual Studio Code), es probable que tsc sea más fácil de usar. Puede instalar la compatibilidad con él con un paquete nuget. Para obtener más información, vea JavaScript y TypeScript en Visual Studio. Para usar babel con Visual Studio, cree un script de compilación o use el Explorador de ejecutores de tareas en Visual Studio con herramientas como el ejecutor de tareas WebPack o el ejecutor de tareas NPM.
Uso de un polyfill
Un polyfill es JavaScript de versión anterior que duplica la funcionalidad de las versiones más recientes de JavaScript. Polyfill funciona en vistas web que no admiten las versiones posteriores de JavaScript. Por ejemplo, el método startsWith de cadena no formaba parte de la versión ES5 de JavaScript, por lo que no se ejecutará en Trident (Internet Explorer 11). Hay bibliotecas de polyfill, escritas en ES5, que definen e implementan un startsWith método. Se recomienda la biblioteca de polyfill core-js .
Para usar una biblioteca de polyfill, cárguela como cualquier otro archivo o módulo de JavaScript. Por ejemplo, puede usar una <script> etiqueta en el archivo HTML de la página principal del complemento (por ejemplo <script src="/js/core-js.js"></script>), o puede usar una import instrucción en un archivo JavaScript (por ejemplo, import 'core-js';). Cuando el motor de JavaScript ve un método como startsWith, primero buscará si hay un método de ese nombre integrado en el lenguaje. Si lo hay, llamará al método nativo. Si, y solo si el método no está integrado, el motor buscará en todos los archivos cargados para él. Por lo tanto, la versión polirellenada no se usa en exploradores que admiten la versión nativa.
La importación de toda la biblioteca core-js importará todas las características de core-js. También puede importar solo los polyfills que requiere el complemento de Office. Para obtener instrucciones sobre cómo hacerlo, consulte Api de CommonJS. La biblioteca core-js tiene la mayoría de los polyfills que necesita. Hay algunas excepciones detalladas en la sección Missing Polyfills de la documentación de core-js. Por ejemplo, no admite fetch, pero puede usar el polyfill de captura .
Para obtener un complemento de ejemplo que usa core.js, vea Complemento de Word Angular2 StyleChecker.