Suportar webviews mais antigos da Microsoft e versões do Office
Os Suplementos do Office são aplicações Web que são apresentadas dentro de iframes quando são executadas no Office na Web. Os Suplementos do Office são apresentados através de um controlo de browser incorporado (também conhecido como webview) quando são executados no Office no Windows ou no Office no Mac. Os controlos de browser incorporados são fornecidos pelo sistema operativo ou por um browser instalado no computador do utilizador.
Importante
Os Webviews do Internet Explorer e do Microsoft Edge Legado ainda são utilizados nos Suplementos do Office
Algumas combinações de plataformas e versões do Office, incluindo versões perpétuas licenciadas em volume através do Office 2019, ainda utilizam os controlos webview fornecidos com o Internet Explorer 11 (denominado "Trident") e o Microsoft Edge Legado (denominado "EdgeHTML") para alojar suplementos, conforme explicado em Browsers e controlos webview utilizados pelos Suplementos do Office. O Internet Explorer 11 foi desativado no Windows 10 e Windows 11 em fevereiro de 2023 e a IU para o iniciar foi removida; mas ainda está instalado com esses sistemas operativos. Assim, o Trident e outras funcionalidades do Internet Explorer ainda podem ser chamados através de programação pelo Office.
Recomendamos (mas não necessite) que suporte estas combinações, pelo menos de forma mínima, ao fornecer aos utilizadores do seu suplemento uma mensagem de falha correta quando o suplemento for iniciado nestas webviews. Tenha estes pontos adicionais em mente:
- O Office na Web já não é aberto no Internet Explorer ou no Microsoft Edge Legado. Consequentemente, o AppSource não testa suplementos no Office na Web nestes browsers.
- O AppSource ainda testa combinações de plataformas e versões de ambiente de trabalho do Office que utilizam Trident ou EdgeHTML. No entanto, apenas emite um aviso quando o suplemento não suporta estas webviews; o suplemento não é rejeitado pelo AppSource.
- A ferramenta Script Lab já não suporta Trident.
Se planeia suportar versões mais antigas do Windows e do Office, o seu suplemento tem de funcionar nos controlos de browser incorporados utilizados por estas versões. Por exemplo, controlos do browser baseados no Internet Explorer 11 (IE11) ou no Microsoft Edge Legado (baseado em EdgeHTML). Para obter informações sobre as combinações do Windows e do Office que utilizam estes controlos de browser, consulte Browsers e controlos webview utilizados pelos Suplementos do Office.
Determinar o webview no qual o suplemento está em execução no runtime
O seu suplemento pode descobrir o webview no qual está a ser executado ao ler a propriedade window.navigator.userAgent . Isto permite que o suplemento forneça uma experiência alternativa ou falhe corretamente. Segue-se um exemplo que determina se o suplemento está em execução no Trident ou 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.
*/
}
Observação
O Microsoft Edge (Chromium) devolve edg/ seguido de um ou mais dígitos de versão e zero ou mais . separadores como agente de utilizador; por exemplo, edg/76.0.167.1. Tenha em atenção que o e não está presente no fim do nome! É "edg", não "edge".
Este JavaScript deve ser o mais cedo possível no processo de arranque do suplemento. Segue-se um exemplo de uma home page do suplemento que aconselha os utilizadores a atualizarem o Office quando for detetado o 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
Nem sempre é uma boa prática ler a userAgent propriedade. Certifique-se de que está familiarizado com o artigo Deteção do browser com o agente do utilizador, incluindo as recomendações e alternativas à leitura userAgent. Em particular, se estiver a fornecer uma experiência de suplemento alternativa para suportar a utilização do Trident, considere utilizar a deteção de funcionalidades em vez de testar o agente do utilizador. No entanto, se estiver apenas a fornecer uma notificação de que o suplemento não funciona no Trident, como neste caso, a utilização userAgent é adequada.
A partir de 24 de julho de 2023, as versões não inglesas do artigo estão desatualizadas em graus variáveis; alguns estão mais de 12 anos desatualizados.
A partir da mesma data, o texto e as tabelas na secção Que parte do agente de utilizador contém as informações que procura? da versão em inglês do artigo já não menciona Trident ou Internet Explorer 11. Na tabela para Nome do Browser e versão, a linha do Internet Explorer 11 foi a seguinte:
| Motor | Deve conter | Não pode conter |
|---|---|---|
| Internet Explorer 11 | Trident/7.0; .*rv:xyz |
Na tabela para Motor de composição, a linha para Trident foi a seguinte:
| Motor | Deve conter | Comentário |
|---|---|---|
| Tridente | Trident/xyz |
O Internet Explorer coloca este fragmento na secção de comentários da cadeia de User-Agent. |
Rever informações de suporte da versão web e do Office
Para obter mais informações sobre como suportar webviews específicos e versões do Office, selecione o separador aplicável.
O motor JavaScript associado ao Trident não suporta versões JavaScript posteriores ao ES5. Para utilizar versões mais modernas do JavaScript ou para utilizar o TypeScript, consulte Suporte para versões recentes do JavaScript.
Importante
O Trident não suporta algumas funcionalidades HTML5, como multimédia, gravação e localização. Se o suplemento tiver de suportar o Trident, tem de estruturar o suplemento para evitar estas funcionalidades não suportadas ou o suplemento tem de detetar quando o Trident está a ser utilizado e fornecer uma experiência alternativa que não utilize as funcionalidades não suportadas. Para obter mais informações, veja Determine the webview the webview the add-in is running in at runtime (Determinar a vista Web em que o suplemento está a ser executado no runtime).
Testar um suplemento no Trident (Internet Explorer)
Veja Testes tridentes.
Suporte para versões recentes do JavaScript
Se quiser utilizar a sintaxe e as funcionalidades de uma versão do JavaScript mais recente do que a suportada no webview ou runtime em que o código está a ser executado ou se pretender utilizar o TypeScript, tem de utilizar um transpiler ou um polifill ou ambos. Por exemplo, um transpiador irá converter sintaxe ou operadores, como o => operador , que é desconhecido no ES5, para ES5. Um polificheiro substitui métodos, tipos e classes de uma versão mais recente do JavaScript em funcionalidades equivalentes numa versão mais antiga.
As subsecções seguintes partem do princípio de que a norma JavaScript de destino é ES5, mas as informações também se aplicam a outros destinos. Por exemplo, se o seu destino for ECMAScript 2016, basta substituir "ES5" por "ECMAScript 2016" (e "pós-ES5" por "pós-ECMAScript 2016") nestas subsecções.
Utilizar um transpiler
Pode escrever o código no TypeScript ou no JavaScript moderno e, em seguida, transpô-lo no tempo de compilação para o JavaScript ES5. Os ficheiros ES5 resultantes são o que carrega para a aplicação Web do suplemento.
Há dois transpilers populares. Ambos podem trabalhar com ficheiros de origem que são TypeScript ou javaScript pós-ES5. Também funcionam com ficheiros React (.jsx e .tsx).
Veja a documentação de qualquer um deles para obter informações sobre como instalar e configurar o transpiler no seu projeto de suplemento. Recomendamos que utilize um executor de tarefas, como Grunt ou WebPack , para automatizar a transpilação. Para obter um suplemento de exemplo que utiliza tsc, consulte Suplemento do Office do Microsoft Graph React. Para obter um exemplo que utiliza babel, veja Suplemento de Armazenamento Offline.
Observação
Se estiver a utilizar o Visual Studio (não o Visual Studio Code), o tsc é provavelmente mais fácil de utilizar. Pode instalar suporte para o mesmo com um pacote nuget. Para obter mais informações, veja JavaScript e TypeScript no Visual Studio. Para utilizar o babel com o Visual Studio, crie um script de compilação ou utilize o Explorador do Task Runner no Visual Studio com ferramentas como o WebPack Task Runner ou o NPM Task Runner.
Utilizar um polifill
Um polyfill é JavaScript de versão anterior que duplica a funcionalidade de versões mais recentes do JavaScript. O polyfill funciona em webviews que não suportam as versões javaScript posteriores. Por exemplo, o método startsWith de cadeia não fazia parte da versão ES5 do JavaScript, pelo que não será executado no Trident (Internet Explorer 11). Existem bibliotecas de polifill, escritas no ES5, que definem e implementam um startsWith método. Recomendamos a biblioteca de polifill core-js .
Para utilizar uma biblioteca de polificheiro, carregue-a como qualquer outro ficheiro ou módulo JavaScript. Por exemplo, pode utilizar uma <script> etiqueta no ficheiro HTML da home page do suplemento (por exemplo <script src="/js/core-js.js"></script>), ou pode utilizar uma instrução import num ficheiro JavaScript (por exemplo, import 'core-js';). Quando o motor JavaScript vê um método como startsWith, primeiro verá se existe um método desse nome incorporado na linguagem. Se existir, chamará o método nativo. Se, e apenas se o método não estiver incorporado, o motor irá procurar em todos os ficheiros carregados. Assim, a versão poli-preenchida não é utilizada em browsers que suportam a versão nativa.
A importação de toda a biblioteca core-js importará todas as funcionalidades core-js. Também pode importar apenas os polifills necessários para o seu Suplemento do Office. Para obter instruções sobre como fazê-lo, veja CommonJS APIs (APIs CommonJS). A biblioteca core-js tem a maioria dos polifills de que precisa. Existem algumas exceções detalhadas na secção Polyfills em Falta da documentação core-js. Por exemplo, não suporta fetch, mas pode utilizar o polyfill de obtenção .
Para obter um suplemento de exemplo que utilize core.js, consulte Suplemento do Word Angular2 StyleChecker.