Práticas recomendadas e regras para a API de Caixa de Diálogo do Office

Este artigo fornece regras, limitações e práticas recomendadas para a API de Caixa de Diálogo do Office, incluindo práticas recomendadas para criar a interface do usuário de uma caixa de diálogo e usar a API em um aplicativo de página única (SPA).

Regras e limitações

• Uma caixa de diálogo só pode navegar até URLs HTTPS, não HTTP.

• A URL que você passa para o método displayDialogAsync deve estar exatamente no mesmo domínio que o próprio suplemento. Ele não pode ser um subdomínio. No entanto, a página que você passa para ela pode redirecionar para uma página em outro domínio.

• Uma página host pode ter apenas uma caixa de diálogo aberta por vez. A página host pode ser um painel de tarefas ou o arquivo de função de um comando de função. Você pode abrir várias caixas de diálogo ao mesmo tempo a partir de botões personalizados da faixa de opções ou itens de menu.

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

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

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

• Quando uma caixa de diálogo é aberta, ela é centralizada na parte superior do aplicativo do Office.

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

• Uma caixa de diálogo aparece na ordem em que é criada.

  Dica

  No Office na Web e no novo Outlook no Windows, se o domínio da caixa de diálogo for diferente daquele do suplemento e aplicar o cabeçalho de resposta Cross-Origin-Opener-Policy: same-origin, o suplemento será impedido de acessar mensagens da caixa de diálogo e os usuários verão o erro 12006. Para evitar esse erro, defina o cabeçalho Cross-Origin-Opener-Policy: unsafe-none ou configure o suplemento e a caixa de diálogo para estarem 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 em seu suplemento. Esses clientes do Outlook usam a propriedade para manter a window.name funcionalidade entre redirecionamentos de página.

Práticas recomendadas

Evite o uso excessivo das 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 guias, consulte o exemplo de SalesTracker do JavaScript do suplemento do Excel .

Criar uma interface do usuário da caixa de diálogo

Para obter práticas recomendadas no design da caixa de diálogo, consulte Caixas de diálogo nos Suplementos do Office.

Lidar com bloqueadores de pop-up com o Office na Web

Se você tentar exibir uma caixa de diálogo ao usar o Office na Web, o bloqueador de pop-ups do navegador poderá bloquear a caixa de diálogo. Para evitar esse problema, o Office na Web solicita que o usuário Permita ou Ignore a abertura da caixa de diálogo.

Se o usuário escolher Permitir, a caixa de diálogo do Office será aberta. Se o usuário escolher Ignorar, o prompt será fechado e a caixa de diálogo do Office não abrirá. Em vez disso, o método retorna o displayDialogAsync erro 12009. Seu código deve capturar esse erro e fornecer uma experiência alternativa que não exija uma caixa de diálogo ou exibir uma mensagem para o usuário informando que o suplemento exige que ele permita a caixa de diálogo. Para obter mais informações sobre o erro 12009, consulte Erros de displayDialogAsync.

Lidar com caixas de diálogo bloqueadas (erro 12009)

Seu suplemento sempre deve lidar com o erro 12009 normalmente. Aqui estão algumas abordagens recomendadas:

• Mostre uma mensagem amigável que explique por que 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 quando possível. Se o suplemento puder funcionar com recursos reduzidos quando a caixa de diálogo estiver bloqueada, ofereça essa alternativa ao usuário.

Desabilitando o prompt

Se você quiser desativar o prompt de permissão ou ignorar, seu código deverá recusar. Faça essa solicitação usando o objeto DialogOptions que você passa para o displayDialogAsync método. Especificamente, incluir promptBeforeOpen: false no objeto. Quando você define essa opção como falsa, o Office na Web não solicita que o usuário permita 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-ups do navegador a bloquear.

Solicitar acesso aos recursos de dispositivo no Office na Web e no novo Outlook no Windows

Se o suplemento exigir acesso às funcionalidades do dispositivo de um usuário, use a API de permissão de dispositivo para solicitar permissões por meio de uma caixa de diálogo. Os recursos do dispositivo incluem a câmera, a geolocalização e o microfone do usuário. Esse requisito se aplica aos seguintes aplicativos do Office.

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

Quando seu suplemento chama Office.context.devicePermission.requestPermissions ou Office.context.devicePermission.requestPermissionsAsync, aparece uma caixa de diálogo com os recursos do dispositivo solicitado e as opções para Permitir, Permitir uma vez ou Negar acesso. Para obter mais informações, confira Exibir, gerenciar e instalar suplementos para o Excel, o PowerPoint e o Word.

Não use o valor _host_info

O Office adiciona automaticamente um parâmetro de consulta nomeado _host_info à URL que é passada para .displayDialogAsync Ele acrescenta esse parâmetro após os parâmetros de consulta personalizados, se houver. Ele não acrescenta esse parâmetro a nenhuma URL subsequente para a qual a caixa de diálogo navega. A Microsoft pode alterar o conteúdo desse valor ou removê-lo completamente, para que seu código não o leia. O mesmo valor é adicionado ao armazenamento de sessões da caixa de diálogo (ou seja, a propriedade Window.sessionStorage ). Novamente, seu código não deve ler nem gravar nesse valor.

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

Você não pode ter mais de uma caixa de diálogo aberta de uma determinada página host, portanto, seu código deve chamar Dialog.close em uma caixa de diálogo aberta antes de chamar displayDialogAsync para abrir outra caixa de diálogo. O close método é assíncrono. Por esse motivo, se você chamar displayDialogAsync imediatamente após uma chamada de , a primeira caixa de closediálogo poderá não ser completamente fechada quando o Office tentar abrir a segunda. Se isso acontecer, o Office retornará 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 retorno de chamada e não retorna um objeto Promise, portanto, não pode ser aguardado com a await palavra-chave ou com um then método. Por esse motivo, use a seguinte técnica quando precisar abrir uma nova caixa de diálogo imediatamente após fechar uma caixa de diálogo: encapsule o código para abrir a nova caixa de diálogo em uma função e projete a função para chamar recursivamente a si mesma se a chamada de displayDialogAsync retornar 12007. O exemplo a seguir mostra como implementar essa 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.
        }
      }
    }
  );
}

Como alternativa, você pode forçar o código a pausar antes que ele tente abrir a segunda caixa de diálogo usando o método setTimeout . O exemplo a seguir mostra como implementar essa 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.
      }
    }
  );
}

Práticas recomendadas para usar a API de Caixa de Diálogo do Office em um SPA

Se o suplemento usar o roteamento do lado do cliente, como os aplicativos de página única (SPAs) normalmente fazem, você poderá passar a URL de uma rota para o método displayDialogAsync em vez da URL de uma página HTML separada. Não use essa abordagem pelos motivos apresentados na seção a seguir.

Problemas com SPAs e a API de Caixa de Diálogo do Office

A caixa de diálogo do Office está em uma nova janela com sua própria instância do mecanismo JavaScript e, portanto, seu próprio contexto de execução completo. Se você passar uma rota, sua página base e todo o seu código de inicialização e inicialização serão executados novamente nesse novo contexto, e todas as variáveis serão definidas com seus valores iniciais na caixa de diálogo. Portanto, essa técnica baixa e inicia uma segunda instância do aplicativo na janela da caixa de diálogo, o que anula parcialmente a finalidade 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 seu próprio armazenamento de sessão (a propriedade Window.sessionStorage ), que não pode ser acessado pelo código no painel de tarefas. A caixa de diálogo e a página host na qual displayDialogAsync foi chamada parecem dois clientes diferentes para o seu servidor. (Para obter um lembrete do que é uma página host, consulte Abrir uma caixa de diálogo de uma página host.)

Portanto, se você passar uma rota para o displayDialogAsync método, não terá realmente um SPA; terá duas instâncias do mesmo SPA. Além disso, grande parte do código na instância do painel de tarefas nunca é usado nessa instância e grande parte do código na instância da caixa de diálogo nunca é usado nessa instância. É como ter dois SPAs no mesmo pacote.

Recomendações da Microsoft

Em vez de passar uma rota do lado do cliente para o displayDialogAsync método, use uma das abordagens a seguir.

• Se o código que você deseja executar na caixa de diálogo for suficientemente complexo, crie dois SPAs diferentes explicitamente; 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 host da caixa de diálogo onde displayDialogAsync foi chamado.
• Na maioria dos cenários, apenas a lógica simples é necessária na caixa de diálogo. Nesses casos, seu projeto é bastante simplificado hospedando uma única página HTML, com JavaScript inserido ou referenciado, no domínio do seu SPA. Passe a URL da página para o métododisplayDialogAsync. Embora essa abordagem signifique que você se desvia da ideia literal de um aplicativo de página única, na verdade não há uma única instância de um SPA ao usar a API de Caixa de Diálogo do Office.

Confira também

• Usar a API de Caixa de Diálogo do Office em suplementos do Office
• Lidar com erros e eventos na caixa de diálogo do Office