Melhores práticas e regras para a API de Caixa de Diálogo do Office

Este artigo fornece regras, limitações 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).

Regras e limitações

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

• O URL que transmitir 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 transmitir à mesma 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. Pode abrir várias caixas de diálogo ao mesmo tempo a partir de botões do friso personalizados ou itens de menu.

• A caixa de diálogo só pode chamar duas APIs do Office:

  • Office.context.ui.messageParent
  • Office.context.requirements.isSetSupported (Para obter mais informações, consulte Especificar as aplicações do Office e os requisitos da API.)

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

• Quando é aberta uma caixa de diálogo, está centrada no ecrã na parte superior da aplicação do Office.

• O utilizador pode mover e redimensionar uma caixa de diálogo.

• É apresentada uma caixa de diálogo pela ordem pela qual é criada.

  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 os seus utilizadores verão o erro 12006. Para evitar este erro, defina o cabeçalho como Cross-Origin-Opener-Policy: unsafe-none ou configure o suplemento e a caixa de diálogo para estar no mesmo domínio.

• No Outlook na Web e no novo Outlook no Windows, não defina a propriedade window.name ao configurar uma caixa de diálogo no seu suplemento. Estes clientes do Outlook utilizam a window.name propriedade para manter a funcionalidade entre redirecionamentos de página.

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 Office na Web

Se tentar apresentar uma caixa de diálogo enquanto utiliza Office na Web, o bloqueador de pop-up do browser poderá bloquear a caixa de diálogo. Para evitar este problema, Office na Web pede ao utilizador para Permitir ou Ignorar a abertura da caixa de diálogo.

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 o erro 12009, veja Errors from displayDialogAsync (Erros de displayDialogAsync).

Processar caixas de diálogo bloqueadas (erro 12009)

O seu suplemento deve sempre processar o erro 12009 corretamente. Seguem-se algumas abordagens recomendadas:

• Mostrar uma mensagem amigável que explica o motivo pelo qual a caixa de diálogo é necessária.

  Office.context.ui.displayDialogAsync(
    "https://www.contoso.com/auth.html",
    { height: 60, width: 30 },
    (asyncResult) => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        if (asyncResult.error.code === 12009) {
          // User blocked the dialog.
          showNotification(
            "Dialog Required",
            "This add-in needs to open a dialog to sign you in. " +
            "Please click the add-in button again and choose 'Allow' when prompted."
          );
        } else {
          // Handle other errors.
          showNotification("Error", `Unable to open dialog: ${asyncResult.error.message}`);
        }
      } else {
        // Dialog opened successfully.
        const dialog = asyncResult.value;
        // ... Handle dialog events here.
      }
    }
  );
  

• Forneça um fluxo de trabalho alternativo sempre que possível. Se o suplemento puder funcionar com capacidades reduzidas quando a caixa de diálogo estiver bloqueada, ofereça essa alternativa ao utilizador.

Desativar o pedido

Se quiser desativar o pedido de permissão/ignorar, o código tem de optar ativamente por não participar. Faça este pedido com o objeto DialogOptions que transmite ao displayDialogAsync método . Especificamente, inclua promptBeforeOpen: false no objeto . Quando define esta opção como falsa, 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 é aberta se o bloqueador de pop-up do browser o bloquear.

Pedir acesso às capacidades do dispositivo no Office na Web e no novo Outlook no Windows

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

• Office na Web (Excel, Outlook, PowerPoint e Word) em execução em browsers baseados em 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 obter mais informações, consulte Ver, gerir e instalar suplementos para o Excel, PowerPoint e Word.

Não utilize o valor _host_info

O Office adiciona automaticamente um parâmetro de consulta com o nome _host_info ao URL que é transmitido para displayDialogAsync. Acrescenta este parâmetro após os parâmetros de consulta personalizados, se existirem. Não acrescenta este parâmetro a quaisquer URLs subsequentes para os quais a caixa de diálogo navegue. A Microsoft pode alterar o conteúdo deste valor ou removê-lo totalmente, pelo que o 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 , a primeira caixa de closediálogo poderá não estar completamente fechada quando o Office tentar abrir a segunda. Se isso acontecer, o Office devolve 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 o await palavra-chave ou com um then método. Por este motivo, utilize 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 displayDialogAsync devoluções 12007. O exemplo seguinte mostra como implementar esta técnica.

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 . O exemplo seguinte mostra como implementar esta abordagem.

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), pode transmitir o URL de uma rota para o método displayDialogAsync em vez do URL de uma página HTML separada. Não utilize esta abordagem pelos motivos indicados na secção seguinte.

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 seu 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. Por isso, esta técnica transfere e inicia uma segunda instância da sua aplicação na janela da caixa de diálogo, 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 passar uma rota para o displayDialogAsync método , não tem realmente um SPA; tem duas instâncias do mesmo SPA. Além disso, grande parte do código na instância do painel de tarefas nunca é utilizado nessa instância e grande parte do código na instância da caixa de diálogo nunca é utilizado nessa instância. É como ter dois SPAs no mesmo pacote.

Recomendações da Microsoft

Em vez de transmitir uma rota do lado do cliente para o displayDialogAsync método , utilize uma das seguintes abordagens.

• 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. Nestes casos, o seu projeto é 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 esta abordagem signifique que se desvia da ideia literal de uma aplicação de página única, não tem realmente uma única instância de SPA quando utiliza a API de Caixa de Diálogo do Office.

Confira também

• Utilizar a API de Caixa de Diálogo do Office nos Suplementos do Office
• Processar erros e eventos na caixa de diálogo do Office