Partilhar via

Práticas recomendadas e regras para a API da caixa de diálogo do Office

  • Artigo

Este artigo fornece regras, gotchas e melhores práticas para a API de caixa de diálogo do Office, incluindo as melhores práticas para conceber a IU de uma caixa de diálogo e utilizar a API numa aplicação de página única (SPA).

Observação

Para se familiarizar com as noções básicas da utilização da API de caixa de diálogo do Office, consulte Utilizar a API de caixa de diálogo do Office nos seus Suplementos do Office.

Consulte também Lidar com erros e eventos com a caixa de diálogo do Office.

Regras e dicas

  • A caixa de diálogo só pode navegar para URLs HTTPS e não PARA HTTP.

  • O URL transmitido para o método displayDialogAsync tem de estar exatamente no mesmo domínio que o próprio suplemento. Não pode ser um subdomínio. No entanto, a página que lhe é transmitida pode redirecionar para uma página noutro domínio.

  • Uma página de anfitrião só pode ter uma caixa de diálogo aberta de cada vez. A página do anfitrião pode ser um painel de tarefas ou o ficheiro de função de um comando de função.

  • Apenas duas APIs do Office podem ser chamadas na caixa de diálogo,

  • Normalmente, a função messageParent deve ser chamada a partir de uma página no mesmo domínio que o próprio suplemento, mas tal não é obrigatório. Para obter mais informações, mensagens entre domínios para o runtime do host.

    Dica

    No Office na Web e no novo Outlook no Windows, se o domínio da sua caixa de diálogo for diferente do do seu suplemento e impor a Política de Abertura de Origens Cruzadas: cabeçalho de resposta da mesma origem , o seu suplemento será impedido de aceder às mensagens a partir da caixa de diálogo e será apresentado o erro 12006 aos seus utilizadores. Para evitar esta situação, tem de definir o cabeçalho como Cross-Origin-Opener-Policy: unsafe-none ou configurar o suplemento e a caixa de diálogo para estar no mesmo domínio.

Práticas recomendadas

Evitar a substituição de caixas de diálogo

Como a sobreposição de elementos de IU não são recomendáveis, evite abrir uma caixa de diálogo em um painel de tarefas a menos que seu cenário o obrigue a fazer isso. Ao considerar como usar a área de superfície de um painel de tarefas, observe que painéis de tarefas podem ter guias. Para obter um exemplo de um painel de tarefas com separadores, veja o exemplo de JavaScript SalesTracker do Suplemento do Excel .

Criar uma IU da caixa de diálogo

Para obter as melhores práticas na estrutura da caixa de diálogo, consulte Caixas de diálogo nos Suplementos do Office.

Processar bloqueadores de pop-up com o Office na Web

Tentar apresentar uma caixa de diálogo ao utilizar o Office na Web pode fazer com que o bloqueador de pop-up do browser bloqueie a caixa de diálogo. Para evitar esta situação, o Office na Web pede ao utilizador para Permitir ou Ignorar a abertura da caixa de diálogo.

O pedido com uma breve descrição e os botões Permitir e Ignorar que um suplemento pode gerar para evitar bloqueadores de pop-up no browser.

Se o utilizador selecionar Permitir, a caixa de diálogo do Office é aberta. Se o utilizador escolher Ignorar, o pedido é fechado e a caixa de diálogo do Office não é aberta. Em vez disso, o método devolve o displayDialogAsync erro 12009. O código deve detetar este erro e fornecer uma experiência alternativa que não exija uma caixa de diálogo ou apresentar uma mensagem ao utilizador a avisar que o suplemento requer que o mesmo permita a caixa de diálogo. (Para obter mais informações sobre 12009, consulte Erros de displayDialogAsync.)

Se, por qualquer motivo, pretender desativar esta funcionalidade, o código tem de optar ativamente por não participar. Faz este pedido com o objeto DialogOptions que é transmitido para o displayDialogAsync método . Especificamente, o objeto deve incluir promptBeforeOpen: false. Quando esta opção está definida como falsa, o Office na Web não pede ao utilizador para permitir que o suplemento abra uma caixa de diálogo e a caixa de diálogo do Office não abre.

Pedir acesso às capacidades dos dispositivos no Office na Web e no novo Outlook no Windows

Se o suplemento necessitar de acesso às capacidades de dispositivo de um utilizador, está disponível uma caixa de diálogo para pedir permissões através da API de permissão do dispositivo. As capacidades do dispositivo incluem a câmara, a geolocalização e o microfone de um utilizador. Isto aplica-se às seguintes aplicações do Office.

  • Office na Web (Excel, Outlook, PowerPoint e Word) em execução em browsers baseados no Chromium, como o Microsoft Edge ou o Google Chrome
  • novo Outlook no Windows

Quando o suplemento chama Office.context.devicePermission.requestPermissions ou Office.context.devicePermission.requestPermissionsAsync, é apresentada uma caixa de diálogo com as capacidades do dispositivo pedidas e as opções para Permitir, Permitir uma vez ou Negar acesso. Para saber mais, consulte Ver, gerir e instalar suplementos para Excel, PowerPoint e Word.

Observação

  • Os suplementos que são executados em clientes de ambiente de trabalho do Office ou em browsers não baseados no Chromium mostram automaticamente uma caixa de diálogo a pedir a permissão de um utilizador. O programador não precisa de implementar a API de permissão do dispositivo nestas plataformas.
  • Os suplementos que são executados no Safari estão impedidos de aceder às capacidades de dispositivo de um utilizador. A API de permissão do dispositivo não é suportada no Safari.

Não utilize o valor _host_info

O Office adiciona automaticamente um parâmetro de consulta chamado _host_info ao URL que é transmitido para displayDialogAsync. É anexado após os parâmetros de consulta personalizados, se existirem. Não é anexado a quaisquer URLs subsequentes para os quais a caixa de diálogo navega. A Microsoft pode alterar o conteúdo deste valor ou removê-lo totalmente, pelo que o seu código não deve lê-lo. O mesmo valor é adicionado ao armazenamento de sessão da caixa de diálogo (ou seja, a propriedade Window.sessionStorage ). Mais uma vez, o código não deve ler nem escrever neste valor.

Abrir outra caixa de diálogo imediatamente após fechar uma

Não pode ter mais do que uma caixa de diálogo aberta a partir de uma determinada página de anfitrião, pelo que o código deve chamar a Caixa de Diálogo.fechar numa caixa de diálogo aberta antes de esta chamar displayDialogAsync para abrir outra caixa de diálogo. O close método é assíncrono. Por este motivo, se ligar displayDialogAsync imediatamente após uma chamada de close, a primeira caixa de diálogo poderá não ter sido completamente fechada quando o Office tentar abrir a segunda. Se isso acontecer, o Office devolverá um erro 12007 : "A operação falhou porque este suplemento já tem uma caixa de diálogo ativa."

O close método não aceita um parâmetro de chamada de retorno e não devolve um objeto Promise, pelo que não pode ser aguardado com a await palavra-chave ou com um then método. Por este motivo, sugerimos a seguinte técnica quando precisar de abrir uma nova caixa de diálogo imediatamente após fechar uma caixa de diálogo: encapsular o código para abrir a nova caixa de diálogo numa função e estruturar a função para se chamar recursivamente se a chamada de devoluções displayDialogAsync12007. Apresentamos um exemplo a seguir.

function openFirstDialog() {
  Office.context.ui.displayDialogAsync("https://MyDomain/firstDialog.html", { width: 50, height: 50},
     (result) => {
      if(result.status === Office.AsyncResultStatus.Succeeded) {
        const dialog = result.value;
        dialog.close();
        openSecondDialog();
      }
      else {
         // Handle errors
      }
    }
  );
}
 
function openSecondDialog() {
  Office.context.ui.displayDialogAsync("https://MyDomain/secondDialog.html", { width: 50, height: 50},
    (result) => {
      if(result.status === Office.AsyncResultStatus.Failed) {
        if (result.error.code === 12007) {
          openSecondDialog(); // Recursive call
        }
        else {
         // Handle other errors
        }
      }
    }
  );
}

Em alternativa, pode forçar o código a colocar em pausa antes de tentar abrir a segunda caixa de diálogo com o método setTimeout . Apresentamos um exemplo a seguir.

function openFirstDialog() {
  Office.context.ui.displayDialogAsync("https://MyDomain/firstDialog.html", { width: 50, height: 50},
     (result) => {
      if(result.status === Office.AsyncResultStatus.Succeeded) {
        const dialog = result.value;
        dialog.close();
        setTimeout(() => { 
          Office.context.ui.displayDialogAsync("https://MyDomain/secondDialog.html", { width: 50, height: 50},
             (result) => { /* callback body */ }
          );
        }, 1000);
      }
      else {
         // Handle errors
      }
    }
  );
}

Melhores práticas para utilizar a API de caixa de diálogo do Office num SPA

Se o suplemento utilizar o encaminhamento do lado do cliente, como normalmente acontecem as aplicações de página única (SPAs), tem a opção de transmitir o URL de uma rota para o método displayDialogAsync em vez do URL de uma página HTML separada. Recomendamos que não o faça pelos motivos indicados abaixo.

Observação

Este artigo não é relevante para o encaminhamento do lado do servidor , como numa aplicação Web baseada no Express.

Problemas com SPAs e a API de caixa de diálogo do Office

A caixa de diálogo do Office encontra-se numa nova janela com a sua própria instância do motor JavaScript e, por conseguinte, é o próprio contexto de execução completo. Se passar uma rota, a sua página base e todo o respetivo código de inicialização e bootstrapping são executados novamente neste novo contexto e todas as variáveis são definidas para os respetivos valores iniciais na caixa de diálogo. Portanto, esta técnica transfere e inicia uma segunda instância da sua aplicação na janela de caixa, o que derrota parcialmente o objetivo de um SPA. Além disso, o código que altera variáveis na janela da caixa de diálogo não altera a versão do painel de tarefas das mesmas variáveis. Da mesma forma, a janela da caixa de diálogo tem o seu próprio armazenamento de sessão (a propriedade Window.sessionStorage ), que não é acessível a partir de código no painel de tarefas. A caixa de diálogo e a página de anfitrião na qual displayDialogAsync foi chamada têm o aspeto de dois clientes diferentes para o servidor. (Para um lembrete do que é uma página de anfitrião, consulte Abrir uma caixa de diálogo a partir de uma página de anfitrião.)

Por isso, se tivesse passado uma rota para o displayDialogAsync método , não teria realmente um SPA; teria duas instâncias do mesmo SPA. Além disso, grande parte do código na instância do painel de tarefas nunca seria utilizado nessa instância e grande parte do código na instância da caixa de diálogo nunca seria utilizado nessa instância. Seria como ter dois SPAs no mesmo grupo.

Recomendações da Microsoft

Em vez de transmitir uma rota do lado do cliente para o displayDialogAsync método , recomendamos que efetue um dos seguintes procedimentos:

  • Se o código que pretende executar na caixa de diálogo for suficientemente complexo, crie explicitamente dois SPAs diferentes; ou seja, ter dois SPAs em pastas diferentes do mesmo domínio. Um SPA é executado na caixa de diálogo e o outro na página de anfitrião da caixa de diálogo onde displayDialogAsync foi chamado.
  • Na maioria dos cenários, só é necessária lógica simples na caixa de diálogo. Nesses casos, o seu projeto será bastante simplificado ao alojar uma única página HTML, com JavaScript incorporado ou referenciado, no domínio do spa. Passe a URL da página para o métododisplayDialogAsync. Embora isto signifique que está a desviar-se da ideia literal de uma aplicação de página única; não tem realmente uma única instância de spa quando está a utilizar a API de caixa de diálogo do Office.