Usar a API de diálogo do Office em suplementos do Office

Use a API de diálogo do Office para abrir caixas de diálogo em seu suplemento do Office. Este artigo fornece orientações para usar a API de Caixa de diálogo em seu Suplemento do Office. Considere abrir uma caixa de diálogo de um painel de tarefas, suplemento de conteúdo ou comando de suplemento para realizar as tarefas a seguir.

• Conecte um usuário com um recurso como Google, Facebook ou identidade da Microsoft. Para obter mais informações, consulte Autenticar com a API de caixa de diálogo do Office.
• Fornecer mais espaço na tela, ou até uma tela inteira, para algumas tarefas no seu suplemento.
• Hospedar um vídeo que seria muito pequeno se confinado a um painel de tarefas.
• Mostrar uma tela de erro, progresso ou entrada.

A imagem abaixo mostra um exemplo de uma caixa de diálogo.

A caixa de diálogo sempre abre no centro da tela. O usuário pode movê-la e redimensioná-la. A janela não é modal - um usuário pode continuar a interagir com o documento no aplicativo do Office e com a página no painel de tarefas, se houver uma.

Abrir uma caixa de diálogo em uma página de host

As APIs JavaScript para Office incluem um objetoDialog e duas funções no namespace Office.context.ui.

Para abrir uma caixa de diálogo, seu código, normalmente uma página em um painel de tarefas, chama o método displayDialogAsync e passa a URL do recurso que você deseja abrir. A página na qual você chama esse método é conhecida como "página host". Por exemplo, se você chamar esse método em script em index.html um painel de tarefas, index.html é a página host da caixa de diálogo que o método abre.

O recurso aberto na página de diálogo geralmente é uma página, mas pode ser um método controlador em um aplicativo MVC, uma rota, um método de serviço Web ou qualquer outro recurso. Neste artigo, "página" ou "site" refere-se ao recurso na caixa de diálogo. O código a seguir é um exemplo simples.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html");

• A URL usa o protocolo HTTPS. Esse protocolo é obrigatório para todas as páginas carregadas em uma caixa de diálogo, não apenas para a primeira página carregada.
• A caixa de diálogo é igual ao domínio da página de host, que pode ser a página em um painel de tarefas ou o arquivo de função de um comando de suplemento. A página, o método do controlador ou outro recurso que você passa para o displayDialogAsync método deve estar no mesmo domínio que a página host.

Depois que a primeira página (ou outro recurso) é carregada, um usuário pode usar links ou outra interface do usuário para navegar para qualquer site (ou outro recurso) que use HTTPS. Também é possível criar a primeira página para redirecionar imediatamente para outro site.

Por padrão, a caixa de diálogo ocupa 80% da altura e largura da tela do dispositivo, mas você pode definir porcentagens diferentes passando um objeto de configuração para o método, conforme mostrado no exemplo a seguir.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 });

Para obter um suplemento de exemplo que faz isso, consulte Tutorial do Excel - Concluído. Para obter mais exemplos que usam displayDialogAsync, consulte Exemplos de código.

Defina os dois valores como 100% para ter uma verdadeira experiência de tela inteira. O máximo efetivo é 99,5%, e a janela ainda é móvel e redimensionável.

Apenas uma caixa de diálogo pode ser aberta em uma janela do host. Tentar abrir outra caixa de diálogo gera um erro. Por exemplo, se um usuário abrir uma caixa de diálogo de um painel de tarefas, ele não poderá abrir uma segunda caixa de diálogo de uma página diferente no painel de tarefas. No entanto, quando uma caixa de diálogo é aberta em um comando de suplemento, o comando abre um arquivo HTML novo (mas não visto) sempre que ele é selecionado. Esse processo cria uma nova janela de host (invisível), para que cada janela possa iniciar sua própria caixa de diálogo. Para obter mais informações, confira Erros de displayDialogAsync.

Aproveite uma opção de desempenho no Office na Web

A displayInIframe propriedade é uma propriedade adicional no objeto de configuração que você passa para displayDialogAsync. Quando você define essa propriedade true e o suplemento é executado em um documento aberto no Office na Web, a caixa de diálogo é aberta como um iframe flutuante em vez de uma janela independente. Essa abordagem faz com que a caixa de diálogo seja aberta mais rapidamente. O exemplo a seguir mostra como usar essa propriedade.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20, displayInIframe: true });

O valor padrão é false, que é o mesmo que omitir a propriedade inteiramente. Se o suplemento não estiver em execução no Office na Web, a displayInIframe propriedade será ignorada.

Envie informações da caixa de diálogo para a página host

O código na caixa de diálogo usa a função messageParent para enviar uma mensagem de cadeia de caracteres para a página host. A string pode ser uma palavra, frase, blob XML, JSON stringificado ou qualquer outra coisa que possa ser serializada em uma string ou convertida em uma string. Para usar o messageParent método, a caixa de diálogo deve primeiro inicializar a API JavaScript do Office.

O exemplo a seguir mostra como inicializar o Office JS e enviar uma mensagem para a página do host.

Office.onReady(() => {
   // Add any initialization code for your dialog here.
});

// Called when dialog signs in the user.
function userSignedIn() {
    Office.context.ui.messageParent(true.toString());
}

O exemplo a seguir mostra como retornar uma cadeia de caracteres JSON contendo informações de perfil.

function userProfileSignedIn(profile) {
    const profileMessage = {
        "name": profile.name,
        "email": profile.email,
    };
    Office.context.ui.messageParent(JSON.stringify(profileMessage));
}

A messageParent função é uma das duas únicas APIs JS do Office que você pode chamar na caixa de diálogo. A outra API JS que você pode chamar na caixa de diálogo é Office.context.requirements.isSetSupported. Para obter informações sobre isso, consulte Especificar aplicativos do Office e requisitos de API. No entanto, na caixa de diálogo, essa API não é compatível com o Outlook 2016 perpétuo licenciado por volume (ou seja, a versão MSI).

Você deve configurar a página do host para receber a mensagem. Adicione um parâmetro de retorno de chamada à chamada original de displayDialogAsync. O retorno de chamada atribui um manipulador ao evento DialogMessageReceived. O exemplo a seguir mostra como fazer isso.

let dialog; // Declare dialog as global for use in later functions.
Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
    (asyncResult) => {
        dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, processMessage);
    }
);

O Office transmite um objeto AsyncResult para o retorno de chamada. Ele representa o resultado de tentativas de abrir a caixa de diálogo, Ele não representa o resultado de nenhum evento na caixa de diálogo. Para saber mais sobre essa distinção, confira Manipular erros e eventos.

• A propriedade value do asyncResult é definida como um objeto Dialog que existe na página host, não no contexto da execução da caixa de diálogo.
• A processMessage função manipula o evento. Você pode dar a ele o nome que desejar.
• A variável dialog é declarada em um escopo mais amplo do que o retorno de chamada porque ela também é referenciada em processMessage.

O exemplo a seguir mostra um manipulador simples para o DialogMessageReceived evento.

function processMessage(arg) {
    const messageFromDialog = JSON.parse(arg.message);
    showUserName(messageFromDialog.name);
}

O Office transmite o objeto arg para o manipulador. Sua message propriedade é a cadeia de caracteres enviada pela chamada de na caixa de messageParent diálogo. Neste exemplo, é uma representação em cadeia de caracteres do perfil de um usuário de um serviço, como a conta Microsoft ou o Google, portanto, é desserializado de volta para um objeto com JSON.parse. A showUserName implementação não é mostrada. Ela pode exibir uma mensagem de boas-vindas personalizada no painel de tarefas.

Quando a interação do usuário com a caixa de diálogo for concluída, seu manipulador de mensagem fechará a caixa de diálogo, conforme mostrado neste exemplo.

function processMessage(arg) {
    dialog.close();
    // Add code to process the message here.
}

O objeto dialog deve ser o mesmo que é retornado pela chamada de displayDialogAsync. Declare o dialog objeto como uma variável global. Ou você pode definir o escopo do dialog objeto para a displayDialogAsync chamada com uma função de retorno de chamada anônima, conforme mostrado no exemplo a seguir. No exemplo, não é necessário fechar a caixa de diálogo, processMessage pois o close método é chamado na função de retorno de chamada anônimo.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
    (asyncResult) => {
        const dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg) => {
            dialog.close();
            processMessage(arg);
        });
      }
    );

Se o suplemento precisar abrir uma página diferente do painel de tarefas depois de receber a mensagem, use o window.location.replace método (ou window.location.href) como a última linha do manipulador. O exemplo a seguir mostra como fazer isso.

function processMessage(arg) {
    // Add code to process the message here.
    window.location.replace("/newPage.html");
    // Alternatively, use the following:
    // window.location.href = "/newPage.html";
}

Para ver um exemplo de um suplemento que faz isso, consulte Inserir gráficos do Excel usando o Microsoft Graph em um Suplemento do PowerPoint.

Mensagens condicionais

Como você pode enviar várias chamadas messageParent a partir da caixa de diálogo, mas tem apenas um manipulador na página host do evento DialogMessageReceived, o manipulador tem que usar a lógica condicional para distinguir mensagens diferentes. Por exemplo, se a caixa de diálogo solicitar que um usuário entre em um provedor de identidade, como conta Microsoft ou Google, ela enviará o perfil do usuário como uma mensagem. Se a autenticação falhar, a caixa de diálogo enviará informações de erro para a página do host, como no exemplo a seguir.

if (loginSuccess) {
    const userProfile = getProfile();
    const messageObject = { messageType: "signinSuccess", profile: userProfile };
    const jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
} else {
    const errorDetails = getError();
    const messageObject = { messageType: "signinFailure", error: errorDetails };
    const jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
}

Sobre o exemplo anterior, observe que:

• A loginSuccess variável é inicializada lendo a resposta HTTP do provedor de identidade.
• A implementação das getProfile funções and getError não é mostrada. Cada uma delas obtém dados de um parâmetro de consulta ou do corpo da resposta HTTP.
• São enviados objetos anônimos de diferentes tipos se a entrada for bem-sucedida ou não. Ambos têm uma propriedade messageType, mas um tem uma propriedade profile e o outro tem uma propriedade error.

O código do manipulador na página host usa o valor da propriedade messageType para ramificar como no exemplo a seguir. A função showUserName é a mesma do exemplo anterior e a função showNotification exibe o erro na interface do usuário da página host.

function processMessage(arg) {
    const messageFromDialog = JSON.parse(arg.message);
    if (messageFromDialog.messageType === "signinSuccess") {
        dialog.close();
        showUserName(messageFromDialog.profile.name);
        window.location.replace("/newPage.html");
    } else {
        dialog.close();
        showNotification("Unable to authenticate user: " + messageFromDialog.error);
    }
}

A showNotification implementação não é mostrada. Pode exibir o status em uma barra de notificação no painel de tarefas.

Mensagens entre domínios para o tempo de execução do host

Depois que a caixa de diálogo for aberta, a caixa de diálogo ou o tempo de execução pai poderá navegar para fora do domínio do suplemento. Se alguma dessas coisas acontecer, uma chamada para messageParent falhará, a menos que seu código especifique o domínio do tempo de execução pai. Adicione um parâmetro DialogMessageOptions à chamada de messageParent para especificar o domínio. Esse objeto tem uma targetOrigin propriedade que especifica o domínio para o qual a mensagem deve ser enviada. Se você não usar o parâmetro, o Office presumirá que o destino é o mesmo domínio que a caixa de diálogo está hospedada no momento.

O exemplo a seguir mostra como enviar messageParent uma mensagem entre domínios.

Office.context.ui.messageParent("Some message", { targetOrigin: "https://resource.contoso.com" });

Se a mensagem não incluir dados confidenciais, você poderá definir como "*", o targetOrigin que permite que ela seja enviada para qualquer domínio. O exemplo a seguir mostra como fazer isso.

Office.context.ui.messageParent("Some message", { targetOrigin: "*" });

Transmitir informações para a caixa diálogo

Seu suplemento pode enviar mensagens da página do host para uma caixa de diálogo usando Dialog.messageChild.

Uso messageChild() da página host

Quando você chama a API de diálogo do Office para abrir uma caixa de diálogo, ela retorna um objeto Dialog . Atribua esse objeto a uma variável com escopo global para que você possa fazer referência a ele a partir de outras funções. O exemplo a seguir mostra como fazer isso.

let dialog; // Declare as global variable.
Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html",
    (asyncResult) => {
        dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, processMessage);
    }
);

function processMessage(arg) {
    dialog.close();

    // Add code to process the message here.

}

Esse Dialog objeto tem um método messageChild que envia qualquer cadeia de caracteres, incluindo dados stringificados, para a caixa de diálogo. Esse método gera um DialogParentMessageReceived evento na caixa de diálogo. Seu código deve lidar com esse evento, conforme mostrado na próxima seção.

Considere um cenário no qual a interface do usuário da caixa de diálogo está relacionada à planilha do Excel ativa no momento e a posição dessa planilha em relação às outras planilhas. No exemplo a seguir, worksheetPropertiesChanged envia as propriedades da planilha ativa para a caixa de diálogo. Os dados são stringificados para que possam ser passados para messageChild.

await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getActiveWorksheet();
    worksheet.load();
    await context.sync();
    worksheetPropertiesChanged(worksheet);
});

...

function worksheetPropertiesChanged(currentWorksheet) {
    const messageToDialog = JSON.stringify(currentWorksheet);
    dialog.messageChild(messageToDialog);
}

Identificador DialogParentMessageReceived na caixa de diálogo

No JavaScript da caixa de diálogo, registre um manipulador para o DialogParentMessageReceived evento usando o método UI.addHandlerAsync . Normalmente, você registra o manipulador na função Office.onReady ou Office.initialize, conforme mostrado no exemplo a seguir. (Um exemplo mais robusto é incluído mais adiante neste artigo.)

Office.onReady(() => {
    Office.context.ui.addHandlerAsync(Office.EventType.DialogParentMessageReceived,onMessageFromParent);
});

Em seguida, defina o onMessageFromParent manipulador. O código a seguir continua o exemplo da seção anterior. Observe que Office passa um argumento para o manipulador e que a message propriedade do objeto de argumento contém a cadeia de caracteres da página host. Neste exemplo, a mensagem é reconvertida em um objeto e o jQuery é usado para definir o título superior da caixa de diálogo para corresponder ao nome da nova planilha.

function onMessageFromParent(arg) {
    const messageFromParent = JSON.parse(arg.message);
    document.querySelector('h1').textContent = messageFromParent.name;
}

É uma prática recomendada verificar se o manipulador está registrado corretamente. Você pode fazer isso passando um retorno de chamada para o addHandlerAsync método. Esse retorno de chamada é executado quando a tentativa de registrar o manipulador é concluída. Use o manipulador para registrar ou mostrar um erro se o manipulador não tiver sido registrado com êxito. O exemplo a seguir mostra como fazer isso. Observe que reportError é uma função, não definida aqui, que registra ou exibe o erro.

Office.onReady(() => {
    Office.context.ui.addHandlerAsync(
        Office.EventType.DialogParentMessageReceived,
        onMessageFromParent,
        onRegisterMessageComplete
    );
});

function onRegisterMessageComplete(asyncResult) {
    if (asyncResult.status !== Office.AsyncResultStatus.Succeeded) {
        reportError(asyncResult.error.message);
    }
}

Mensagens condicionais da página pai para a caixa de diálogo

Como a página do host pode fazer várias messageChild chamadas, mas a caixa de diálogo tem apenas um manipulador para o DialogParentMessageReceived evento, o manipulador deve usar a lógica condicional para distinguir mensagens diferentes. Você pode estruturar essa lógica condicional de uma maneira que seja precisamente paralela à forma como você estrutura o sistema de mensagens condicional quando a caixa de diálogo envia uma mensagem para a página do host, conforme descrito em Mensagens condicionais.

Mensagens entre domínios para o tempo de execução da caixa de diálogo

Depois que a caixa de diálogo for aberta, a caixa de diálogo ou o tempo de execução pai poderá navegar para fora do domínio do suplemento. Se qualquer uma dessas coisas acontecer, as chamadas falharão messageChild , a menos que seu código especifique o domínio do tempo de execução da caixa de diálogo. Adicione um parâmetro DialogMessageOptions à chamada de messageChild para especificar o domínio. Esse objeto tem uma targetOrigin propriedade que especifica o domínio para o qual a mensagem deve ser enviada. Se você não usar o parâmetro, o Office presumirá que o destino é o mesmo domínio que o runtime pai está hospedando no momento.

O exemplo a seguir mostra como enviar messageChild uma mensagem entre domínios.

dialog.messageChild(messageToDialog, { targetOrigin: "https://resource.contoso.com" });

Se a mensagem não incluir dados confidenciais, você poderá definir como "*", o targetOrigin que permite que ela seja enviada para qualquer domínio. O exemplo a seguir mostra como definir o targetOrigin.

dialog.messageChild(messageToDialog, { targetOrigin: "*" });

O manifesto do suplemento especifica domínios confiáveis. No manifesto unificado para Microsoft 365, especifique esse domínio na propriedade "validDomains". No manifesto somente do suplemento, especifique esse domínio no <AppDomains> elemento.

Mas o tempo de execução que hospeda a caixa de diálogo não pode acessar o manifesto e, portanto, determinar se o domínio do qual a mensagem vem é confiável. Você deve usar o DialogParentMessageReceived manipulador para determinar isso. O objeto que é passado para o manipulador contém o domínio que está atualmente hospedado no pai como sua origin propriedade. O exemplo a seguir mostra como usar a propriedade.

function onMessageFromParent(arg) {
    if (arg.origin === "https://addin.fabrikam.com") {
        // Process the message.
    } else {
        // Signal the parent page to close the dialog.
        const messageObject = { messageType: "untrustedDomain" };
        Office.context.ui.messageParent(messageObject);
    }
}

Por exemplo, seu código pode usar a função Office.onReady ou Office.initialize para armazenar uma matriz de domínios confiáveis em uma variável global. Em seguida, a arg.origin propriedade pode ser verificada em relação a essa lista no manipulador.

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\AllowedDialogCommunicationDomains]
"My trusted domain"="https://www.contoso.com"
"Another trusted domain"="https://fabrikam.com"

Fechar a caixa de diálogo

Você pode adicionar um botão à caixa de diálogo que a fecha. Para fazer isso, o manipulador de eventos de clique do botão deve usar messageParent para informar à página do host que o botão foi clicado. O exemplo a seguir mostra como implementar essa funcionalidade.

function closeButtonClick() {
    const messageObject = { messageType: "dialogClosed" };
    const jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
}

O manipulador de página do host para DialogMessageReceived chamadas dialog.close, conforme mostrado neste exemplo. (Veja exemplos anteriores que mostram como o objeto dialog é inicializado.)

function processMessage(arg) {
    const messageFromDialog = JSON.parse(arg.message);
    if (messageFromDialog.messageType === "dialogClosed") {
       dialog.close();
    }
}

Mesmo que você não adicione sua própria interface do usuário de diálogo de fechamento, um usuário final pode fechar a caixa de diálogo escolhendo o X no canto superior direito. Essa ação aciona o evento DialogEventReceived. Se o painel de host precisar saber quando esse evento acontece, ele deverá declarar um manipulador para esse evento. Para obter mais informações, consulte Erros e eventos na caixa de diálogo.

Não use window.open.

Não use o método padrão do navegador window.open() para abrir caixas de diálogo ou janelas pop-up em Suplementos do Office. O window.open() método não funciona de forma confiável nos diferentes controles de navegador e modo de exibição da Web em que os suplementos do Office são executados. Você pode encontrar os seguintes problemas com window.open().

• Não funciona em contextos de iframe: quando o suplemento é executado no Office na Web, o painel de tarefas está dentro de um iframe. Por motivos de segurança, muitos navegadores bloqueiam ou restringem window.open() severamente as chamadas de iframes.
• Bloqueado por bloqueadores de pop-up: os bloqueadores de pop-up baseados em navegador bloqueiam window.open() chamadas e o comportamento varia entre os navegadores.
• Comportamento inconsistente do modo de exibição da Web: os controles de modo de exibição da Web incorporados usados pelos aplicativos da área de trabalho do Office lidam de window.open() maneira diferente dos navegadores completos, levando a um comportamento imprevisível.
• Sem garantia multiplataforma: mesmo que funcione window.open() em uma plataforma (como a área de trabalho do Windows), ele pode falhar completamente em outra plataforma (como o Office na Web ou no Mac).

Sempre use a API de Caixa de Diálogo do Office. A API de Diálogo do Office (Office.context.ui.displayDialogAsync) foi projetada especificamente para funcionar de forma consistente em todas as plataformas do Office e ambientes de tempo de execução. Ele fornece uma funcionalidade de diálogo confiável que funciona se o suplemento estiver sendo executado em um navegador, um controle de modo de exibição da Web ou um iframe.

Para abrir URLs externas em uma janela separada do navegador (não para autenticação ou troca de dados com seu suplemento), use o Office.context.ui.openBrowserWindow(url) método, onde url normalmente é uma URL HTTPS.

Exemplos de código

Todos os exemplos a seguir usam displayDialogAsync. Alguns têm servidores baseados em NodeJS e outros têm servidores ASP.NET/IIS-based, mas a lógica de usar o método é a mesma, independentemente de como o lado do servidor do suplemento é implementado.

• Tutorial do Excel - Concluído
• Gerencie a faixa de opções e a interface do usuário do painel de tarefas e execute o código no documento aberto
• Obter dados do OneDrive usando o Microsoft Graph e o MSAL.NET em um suplemento do Office
• Obtenha dados do OneDrive usando o Microsoft Graph e MSAL.js em um suplemento do Office
• Suplemento do Office Exemplo de monetização de SAAS
• Obter pastas de trabalho do Excel usando o Microsoft Graph e o MSAL em um suplemento do Outlook
• SSO do Suplemento do Outlook

Confira também

• Conjuntos de requisitos da API de Caixa de Diálogo
• Práticas recomendadas e regras para a API da caixa de diálogo do Office
• Autenticar com a API de caixa de diálogo do Office
• Usar a caixa de diálogo do Office para mostrar um vídeo
• Manipulando erros e eventos na caixa de diálogo do Office
• Runtimes em Suplementos do Office