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

Utilize a API de caixa de diálogo do Office para abrir caixas de diálogo no 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 a partir de um painel de tarefas, suplemento de conteúdo ou comando de suplemento para fazer o seguinte:

• Inicie sessão num utilizador 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 fosse confinado em um painel de tarefas.

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

A caixa de diálogo é sempre aberta no centro do ecrã. O usuário pode movê-la e redimensioná-la. A janela não émodal – um utilizador pode continuar a interagir com o documento na aplicação do Office e com a página no painel de tarefas, se existir um.

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, geralmente uma página no painel de tarefas chama o método displayDialogAsync e transmite a ele a URL do recurso que você deseja abrir. A página em que esse método é chamado é conhecida como "página host". Por exemplo, se você chamar esse método no script index.html em um painel de tarefas, index.html será a página do 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 seguinte é um exemplo simples.

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

• A URL usa o protocolo HTTPS. Isso é obrigatório para todas as páginas carregadas em uma caixa 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. É necessário que a página, o método do controlador ou outro recurso transmitido para o displayDialogAsync método tenha de estar no mesmo domínio que a página do anfitrião.

Após o carregamento da primeira página (ou de outro recurso), um usuário pode usar links ou outra interface de usuário para qualquer site (ou outro recurso) que usa HTTPS. Também é possível criar a primeira página para redirecionar imediatamente para outro site.

Por padrão, a caixa de diálogo ocupará 80% da altura e da largura na tela do dispositivo, mas você pode definir porcentagens diferentes. Basta transmitir um objeto de configuração para o método, como mostra o exemplo a seguir.

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

Para obter um suplemento de exemplo que faça isto, consulte Criar Suplementos do Office para Excel. Para obter mais exemplos que utilizam displayDialogAsynco , veja Exemplos de código.

Defina os dois valores como 100% para ter uma verdadeira experiência de tela inteira. O máximo efetivo é de 99,5%, e a janela continua a ser moví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 utilizador abrir uma caixa de diálogo a partir de um painel de tarefas, não poderá abrir uma segunda caixa de diálogo a partir 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. Isso cria uma nova janela do host (não vista) 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 propriedade displayInIframe é uma propriedade adicional no objeto de configuração que você pode passar para odisplayDialogAsync. Quando essa propriedade for definida como true e o suplemento estiver em execução em um documento aberto no Office Online, a caixa de diálogo será aberta como um iframe flutuante, em vez de uma janela independente, o que faz com que ela seja aberta mais rapidamente. Apresentamos um exemplo a seguir.

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 a ser executado no Office na Web, o displayInIframe é ignorado.

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

O código na caixa de diálogo utiliza a função messageParent para enviar uma mensagem de cadeia para a página do anfitrião. A cadeia pode ser uma palavra, frase, blob XML, JSON stringified ou qualquer outra coisa que possa ser serializada para uma cadeia ou ser fundida numa cadeia. Para utilizar o messageParent método , a caixa de diálogo tem de inicializar primeiro a API JavaScript do Office.

O exemplo seguinte mostra como inicializar o Office JS e enviar uma mensagem para a página de anfitrião.

Office.onReady(function() {
   // 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 seguinte mostra como devolver uma cadeia JSON que contém 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 APIs do Office JS que podem ser chamadas na caixa de diálogo. A outra API JS que pode ser chamada na caixa de diálogo é Office.context.requirements.isSetSupported. Para obter informações sobre o mesmo, consulte Especificar as aplicações do Office e os requisitos da API. No entanto, na caixa de diálogo, esta API não é suportada no Outlook 2016 perpétuo licenciado em volume (ou seja, na versão MSI).

A página host deve ser configurada para receber a mensagem. Você pode fazer isso adicionando um parâmetro de retorno de chamada à chamada original de displayDialogAsync. O retorno de chamada atribui um manipulador ao evento DialogMessageReceived. Apresentamos um exemplo a seguir.

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},
    function (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, Ela não representa o resultado de eventos na caixa 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.
• O processMessage é a função que 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.

Veja a seguir um exemplo simples de um manipulador para o evento DialogMessageReceived.

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

O Office transmite o objeto arg para o manipulador. A message respetiva propriedade é a cadeia enviada pela chamada de na caixa de messageParent diálogo. Neste exemplo, é uma representação com cadeias de carateres do perfil de um utilizador a partir de um serviço, como a conta Microsoft ou a Google, pelo que é anulada a serialização para um objeto com JSON.parse. A showUserName implementação não é apresentada. 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();
    // message processing code goes here;
}

O objeto dialog deve ser o mesmo que é retornado pela chamada de displayDialogAsync. Tem de declarar o dialog objeto como uma variável global. Em alternativa, pode definir o âmbito do dialog objeto para a displayDialogAsync chamada com uma função de chamada de retorno anónima, conforme mostrado no exemplo seguinte. No exemplo, processMessage não precisa de fechar a caixa de diálogo, uma vez que o close método é chamado na função de chamada de retorno anónima.

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

Se o suplemento precisa abrir uma página diferente do painel de tarefas depois de receber a mensagem, é possível usar o método window.location.replace (ou window.location.href) como a última linha do manipulador. Apresentamos um exemplo a seguir.

function processMessage(arg) {
    // message processing code goes here;
    window.location.replace("/newPage.html");
    // Alternatively ...
    // 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 pedir a um utilizador para iniciar sessão num fornecedor de identidade, como a conta Microsoft ou a Google, envia o perfil do utilizador como uma mensagem. Se a autenticação falhar, a caixa de diálogo envia informações de erro para a página do anfitrião, como no exemplo seguinte.

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, tenha em atenção:

• A variável loginSuccess poderia ser inicializada por meio da leitura da resposta HTTP no provedor de identidade.
• A implementação das getProfile funções e getError não é apresentada. 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 é apresentada. Pode apresentar o estado numa barra de notificação no painel de tarefas.

Mensagens entre domínios para o runtime do anfitrião

Após a abertura da caixa de diálogo, a caixa de diálogo ou o runtime principal podem sair do domínio do suplemento. Se alguma destas coisas acontecer, uma chamada de messageParent irá falhar, a menos que o código especifique o domínio do runtime principal. Para tal, adicione um parâmetro DialogMessageOptions à chamada de messageParent. Este objeto tem uma targetOrigin propriedade que especifica o domínio para o qual a mensagem deve ser enviada. Se o parâmetro não for utilizado, o Office pressupõe que o destino é o mesmo domínio que a caixa de diálogo está atualmente a alojar.

Segue-se um exemplo de utilização messageParent para enviar uma mensagem entre domínios.

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

Se a mensagem não incluir dados confidenciais, pode definir como targetOrigin "*" que permite que sejam enviados para qualquer domínio. Apresentamos um exemplo a seguir.

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

Transmitir informações para a caixa diálogo

O suplemento pode enviar mensagens da página do anfitrião para uma caixa de diálogo através de Dialog.messageChild.

Utilizar messageChild() a partir da página do anfitrião

Quando chama a API de caixa de diálogo do Office para abrir uma caixa de diálogo, é devolvido um objeto caixa de diálogo . Deve ser atribuído a uma variável que tenha âmbito global para que possa referenciá-la a partir de outras funções. Apresentamos um exemplo a seguir.

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

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

  // message processing code goes here;

}

Este Dialog objeto tem um método messageChild que envia qualquer cadeia, incluindo dados com cadeias de carateres, para a caixa de diálogo. Esta ação gera um DialogParentMessageReceived evento na caixa de diálogo. O código deve processar este evento, conforme mostrado na secção seguinte.

Considere um cenário em que a IU da caixa de diálogo está relacionada com a folha de cálculo atualmente ativa e a posição dessa folha de cálculo relativamente às outras folhas de cálculo. No exemplo seguinte, sheetPropertiesChanged envia as propriedades da folha de cálculo do Excel para a caixa de diálogo. Neste caso, a folha de cálculo atual tem o nome "A Minha Folha" e é a segunda folha no livro. Os dados são encapsulados num objeto e agrupados para que possam ser transmitidos para messageChild.

function sheetPropertiesChanged() {
    const messageToDialog = JSON.stringify({
                               name: "My Sheet",
                               position: 2
                           });

    dialog.messageChild(messageToDialog);
}

Handle DialogParentMessageReceived na caixa de diálogo

No JavaScript da caixa de diálogo, registe um processador para o DialogParentMessageReceived evento com o método UI.addHandlerAsync . Normalmente, isto é feito na função Office.onReady ou Office.initialize, conforme mostrado no seguinte. (Um exemplo mais robusto é incluído mais adiante neste artigo.)

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

Em seguida, defina o onMessageFromParent processador. O código seguinte continua o exemplo da secção anterior. Tenha em atenção que o Office transmite um argumento ao processador e que a message propriedade do objeto de argumento contém a cadeia da página do anfitrião. Neste exemplo, a mensagem é reconvertida para um objeto e o jQuery é utilizado para definir o cabeçalho superior da caixa de diálogo para corresponder ao novo nome da folha de cálculo.

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

Recomendamos que verifique se o processador está corretamente registado. Pode fazê-lo ao transmitir uma chamada de retorno para o addHandlerAsync método . Esta ação é executada quando a tentativa de registar o processador for concluída. Utilize o processador para registar ou mostrar um erro se o processador não tiver sido registado com êxito. Apresentamos um exemplo a seguir. Tenha em atenção que reportError é uma função, não definida aqui, que regista ou apresenta o erro.

Office.onReady(function () {
  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 principal para a caixa de diálogo

Uma vez que pode fazer várias chamadas messageChild a partir da página do anfitrião, mas tem apenas um processador na caixa de diálogo do DialogParentMessageReceived evento, o processador tem de utilizar a lógica condicional para distinguir diferentes mensagens. Pode fazê-lo de uma forma precisamente paralela à forma como estruturaria as mensagens condicionais quando a caixa de diálogo está a enviar uma mensagem para a página do anfitrião, conforme descrito em Mensagens condicionais.

Mensagens entre domínios para o runtime da caixa de diálogo

Após a abertura da caixa de diálogo, a caixa de diálogo ou o runtime principal podem sair do domínio do suplemento. Se alguma destas coisas acontecer, as chamadas para irão falhar, a messageChild menos que o código especifique o domínio do runtime da caixa de diálogo. Para tal, adicione um parâmetro DialogMessageOptions à chamada de messageChild. Este objeto tem uma targetOrigin propriedade que especifica o domínio para o qual a mensagem deve ser enviada. Se o parâmetro não for utilizado, o Office assume que o destino é o mesmo domínio que o runtime principal está atualmente a alojar.

Segue-se um exemplo de utilização messageChild para enviar uma mensagem entre domínios.

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

Se a mensagem não incluir dados confidenciais, pode definir como targetOrigin "*" que permite que sejam enviados para qualquer domínio. Apresentamos um exemplo a seguir.

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

Uma vez que o runtime que está a alojar a caixa de diálogo não consegue aceder à <secção AppDomains> do manifesto e, assim, determinar se o domínio a partir do qual a mensagem vem é fidedigno, tem de utilizar o DialogParentMessageReceived processador para determinar isto. O objeto que é transmitido para o processador contém o domínio que está atualmente alojado no elemento principal como a respetiva origin propriedade. Segue-se um exemplo de como utilizar a propriedade .

function onMessageFromParent(arg) {
    if (arg.origin === "https://addin.fabrikam.com") {
        // process message
    } else {
        dialog.close();
        showNotification("Messages from " + arg.origin + " aren't accepted.");
    }
}

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

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 implementar um botão na caixa de diálogo para fechá-la. Para fazer isso, o manipulador de eventos de clique do botão deve usar messageParent para informar a página host em que o botão foi clicado. Apresentamos um exemplo a seguir.

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

O manipulador de página host de DialogMessageReceived poderia chamar dialog.close, como 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 quando você não tem sua própria interface de usuário de diálogo de fechar, um usuário final pode fechar a caixa de diálogo escolhendo a opção X no canto superior direito. Essa ação aciona o evento DialogEventReceived. Se seu painel do host precisar saber quando isso acontece, ele deverá declarar um manipulador para esse evento. Confira a seção Erros e eventos na caixa de diálogo para ver os detalhes.

Exemplos de código

Todos os exemplos seguintes utilizam displayDialogAsync. Alguns têm servidores baseados em NodeJS e outros têm servidores ASP.NET/IIS-based, mas a lógica de utilização do método é a mesma, independentemente da forma como o lado do servidor do suplemento é implementado.

• Conteúdo de Formação/Criar Suplementos
• Suplemento do Office no Microsoft Graph ASPNET
• Suplemento do Office Microsoft Graph React
• SSO do NodeJS do Suplemento do Office
• SSO do ASPNET do Suplemento do Office
• Exemplo de Monetização saas do Suplemento do Office
• Suplemento do Outlook no Microsoft Graph ASPNET
• SSO do Suplemento do Outlook
• Visualizador de Tokens do Suplemento do Outlook
• Mensagem Acionável do Suplemento do Outlook
• Partilha de Suplementos do Outlook no OneDrive
• Gráfico De Inserção de ASPNET do Suplemento PowerPoint
• Cenário de Runtime Partilhado do Excel

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
• Utilizar a caixa de diálogo do Office para mostrar um vídeo
• Manipulando erros e eventos na caixa de diálogo do Office
• Runtimes nos Suplementos do Office