Suporte a versões mais antigas da Webviews da Microsoft e do Office

  • Artigo

Os suplementos do Office são aplicativos Web exibidos dentro de iframes ao executar em Office na Web. Os suplementos do Office são exibidos usando um controle de navegador inserido (também conhecido como webview) ao executar no Office no Windows ou office no Mac. Os controles de navegador inseridos são fornecidos pelo sistema operacional ou por um navegador instalado no computador do usuário.

Importante

Webviews de Explorer e Versão Prévia do Microsoft Edge da Internet ainda são usados em Suplementos do Office

Algumas combinações de plataformas e versões do Office, incluindo versões perpétuas licenciadas por volume por meio do Office 2019, ainda usam os controles webview que vêm com o Internet Explorer 11 (chamado de "Trident") e Versão Prévia do Microsoft Edge (chamado "EdgeHTML") para hospedar suplementos, conforme explicado em Navegadores e controles webview usados pelos Suplementos do Office. A internet Explorer 11 foi desabilitada em Windows 10 e Windows 11 em fevereiro de 2023, e a interface do usuário para iniciá-la foi removida; mas ainda está instalada com esses sistemas operacionais. Portanto, o Trident e outras funcionalidades da Internet Explorer ainda podem ser chamados programaticamente pelo Office.

Recomendamos (mas não requer) que você dê suporte a essas combinações, pelo menos de forma mínima, fornecendo aos usuários do seu suplemento uma mensagem de falha graciosa quando seu suplemento é iniciado nessas visões da Web. Tenha esses pontos adicionais em mente:

  • Office na Web não é mais aberto na Internet Explorer ou Versão Prévia do Microsoft Edge. Consequentemente, o AppSource não testa suplementos em Office na Web nesses navegadores.
  • O AppSource ainda testa combinações de versões da plataforma e da área de trabalho do Office que usam Trident ou EdgeHTML. No entanto, ele só emite um aviso quando o suplemento não dá suporte a essas visões da Web; o suplemento não é rejeitado pelo AppSource.
  • A ferramenta Script Lab não dá mais suporte ao Trident.

Se você planeja dar suporte a versões mais antigas do Windows e do Office, seu suplemento deve funcionar nos controles de navegador inseriveis usados por essas versões. Por exemplo, controles de navegador com base na Internet Explorer 11 (IE11) ou Versão Prévia do Microsoft Edge (baseado em EdgeHTML). Para obter informações sobre quais combinações do Windows e do Office usam esses controles de navegador, consulte Navegadores e controles webview usados pelos Suplementos do Office.

Determinar a visão da Web em que o suplemento está em execução no runtime

Seu suplemento pode descobrir a visão da Web em que ele está em execução lendo a propriedade window.navigator.userAgent . Isso permite que o suplemento forneça uma experiência alternativa ou falhe graciosamente. Veja a seguir um exemplo que determina se o suplemento está em execução em 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) retorna edg/ seguido por um ou mais dígitos de versão e zero ou mais . separadores como o agente de usuário; por exemplo, edg/76.0.167.1. Observe que o e não está presente no final do nome! É "edg", não "edge".

Este JavaScript deve ser o mais cedo possível no processo de inicialização do suplemento. Veja a seguir um exemplo de uma home page de suplemento que aconselha os usuários a atualizar o Office quando o Trident for detectado.

<!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. Verifique se você está familiarizado com o artigo, detecção de navegador usando o agente de usuário, incluindo as recomendações e alternativas à leitura userAgent. Em particular, se você estiver fornecendo uma experiência de suplemento alternativa para dar suporte ao uso do Trident, considere usar a detecção de recursos em vez de testar para o agente de usuário. Mas se você estiver apenas fornecendo uma notificação de que o suplemento não funciona no Trident, como nesse caso, usar userAgent é apropriado.

A partir de 24 de julho de 2023, as versões não em inglês do artigo estão todas desatualizadas em diferentes graus; alguns estão desatualizados há mais de 12 anos.

A partir da mesma data, o texto e as tabelas na seção Qual parte do agente de usuário contém as informações que você está procurando? da versão em inglês do artigo não menção Trident ou Internet Explorer 11. Na tabela nome e versão do navegador, a linha para Internet Explorer 11 foi a seguinte:

Motor Deve conter Não deve conter
Internet Explorer 11 Trident/7.0; .*rv:xyz

Na tabela do mecanismo renderização, a linha para Trident foi a seguinte:

Motor Deve conter Comentário
Tridente Trident/xyz O Explorer da Internet coloca esse fragmento na seção de comentários da cadeia de caracteres User-Agent.

Examinar informações de suporte à versão do Webview e do Office

Para obter mais informações sobre como dar suporte a visões web específicas e versões do Office, selecione a guia aplicável.

O mecanismo JavaScript associado ao Trident não dá suporte a versões JavaScript posteriores ao ES5. Para usar versões mais modernas do JavaScript ou usar TypeScript, consulte Suporte para versões recentes do JavaScript.

Importante

O Trident não dá suporte a alguns recursos HTML5, como mídia, gravação e localização. Se o suplemento precisar dar suporte ao Trident, você deve projetar o suplemento para evitar esses recursos sem suporte ou o suplemento deve detectar quando o Trident está sendo usado e fornecer uma experiência alternativa que não use os recursos sem suporte. Para obter mais informações, consulte Determinar a visão da Web em que o suplemento está em execução no runtime.

Testar um suplemento no Trident (Explorer da Internet)

Consulte Teste do Trident.

Suporte para versões recentes do JavaScript

Se você quiser usar a sintaxe e os recursos de uma versão do JavaScript mais recente do que aquela com suporte no webview ou no runtime em que seu código está em execução ou deseja usar TypeScript, você deve usar um transpiler ou um polifill ou ambos. Por exemplo, um transpiler converterá sintaxe ou operadores, como o => operador, que é desconhecido no ES5, em ES5. Um polifill substitui métodos, tipos e classes de uma versão mais recente do JavaScript em funcionalidade equivalente em uma versão mais antiga.

As subseções a seguir pressupõem que o padrão JavaScript de destino seja ES5, mas as informações também se aplicam a outros destinos. Por exemplo, se seu destino for ECMAScript 2016, basta substituir "ES5" por "ECMAScript 2016" (e "pós-ES5" por "pós-ECMAScript 2016") nessas subseções.

Usar um transpiler

Você pode escrever seu código no TypeScript ou javaScript moderno e transpilá-lo em tempo de compilação no JavaScript ES5. Os arquivos ES5 resultantes são o que você carrega no aplicativo Web do seu suplemento.

Há dois transpiladores populares. Ambos podem trabalhar com arquivos de origem que são TypeScript ou JavaScript pós-ES5. Eles também funcionam com React arquivos (.jsx e .tsx).

Consulte a documentação de qualquer um deles para obter informações sobre como instalar e configurar o transpiler em seu projeto de suplemento. Recomendamos que você use um gerenciador de tarefas, como Grunt ou WebPack , para automatizar a transpilação. Para obter um suplemento de exemplo que usa tsc, consulte o suplemento do Office Microsoft Graph React. Para obter um exemplo que usa babel, consulte Suplemento de armazenamento offline.

Observação

Se você estiver usando o Visual Studio (não Visual Studio Code), o tsc provavelmente será mais fácil de usar. Você pode instalar o suporte para ele com um pacote nuget. Para obter mais informações, confira JavaScript e TypeScript no Visual Studio. Para usar babel com o Visual Studio, crie um script de build ou use o Explorer do Gerenciador de Tarefas no Visual Studio com ferramentas como o Gerenciador de Tarefas WebPack ou o Gerenciador de Tarefas do NPM.

Usar 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 dão suporte às versões posteriores do JavaScript. Por exemplo, o método startsWith de cadeia de caracteres não fazia parte da versão ES5 do JavaScript e, portanto, não será executado no Trident (Internet Explorer 11). Há bibliotecas de polifill, escritas no ES5, que definem e implementam um startsWith método. Recomendamos a biblioteca de polifill core-js .

Para usar uma biblioteca de polifill, carregue-a como qualquer outro arquivo ou módulo JavaScript. Por exemplo, você pode usar uma <script> marca no arquivo HTML da página inicial do suplemento (por exemplo <script src="/js/core-js.js"></script>), ou pode usar uma import instrução em um arquivo JavaScript (por exemplo, import 'core-js';). Quando o mecanismo JavaScript vir um método como startsWith, ele primeiro procurará para ver se há um método desse nome integrado ao idioma. Se houver, ele chamará o método nativo. Se, e somente se, o método não for interno, o mecanismo examinará todos os arquivos carregados para ele. Portanto, a versão polyfilled não é usada em navegadores que dão suporte à versão nativa.

Importar toda a biblioteca core-js importará todos os recursos core-js. Você também pode importar apenas os polífilis necessários para o suplemento do Office. Para obter instruções sobre como fazer isso, consulte APIs CommonJS. A biblioteca core-js tem a maioria dos polífilis de que você precisa. Há algumas exceções detalhadas na seção Polyfills Ausentes da documentação core-js. Por exemplo, ele não dá suporte fetcha , mas você pode usar o polyfill fetch .

Para obter um suplemento de exemplo que usa core.js, consulte Word Suplemento Angular2 StyleChecker.

Confira também