Compartilhar via

Office.UI interface

  • Referência
Pacote:
office

Fornece objetos e métodos para criar e manipular componentes da IU, como caixas de diálogo, nos seus Suplementos do Office.

Para obter orientações sobre como configurar caixas de diálogo, consulte Utilizar a API de Caixa de Diálogo nos seus Suplementos do Office.

Comentários

Exemplos

// Get an Office.UI object and use it to open a dialog with a specified size. 
const uiContext = Office.context.ui;
uiContext.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 });

Métodos

addHandlerAsync(eventType, handler, options, callback)

Adiciona um processador de eventos ao objeto com o tipo de evento especificado.
addHandlerAsync(eventType, handler, callback)

Adiciona um processador de eventos ao objeto com o tipo de evento especificado.
closeContainer()

Fecha o contêiner de interface de usuário onde o JavaScript está sendo executado.
displayDialogAsync(startAddress, options, callback)

Apresenta uma caixa de diálogo para mostrar ou recolher informações do utilizador ou para facilitar a navegação na Web.
displayDialogAsync(startAddress, callback)

Apresenta uma caixa de diálogo para mostrar ou recolher informações do utilizador ou para facilitar a navegação na Web.
messageParent(message, messageOptions)

Fornece uma mensagem da caixa de diálogo a sua página pai/de abertura.
openBrowserWindow(url)

Abre uma janela do browser e carrega o URL especificado.

Detalhes do método

addHandlerAsync(eventType, handler, options, callback)

Adiciona um processador de eventos ao objeto com o tipo de evento especificado.

addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, options: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Parâmetros

eventType
Office.EventType

Especifica o tipo de evento a ser adicionado. Tem de ser Office.EventType.DialogParentMessageReceived.

handler

(result: Office.DialogParentMessageReceivedEventArgs) => void

A função de processador de eventos a adicionar, cujo único parâmetro é do tipo Office.DialogParentMessageReceivedEventArgs.

options
Office.AsyncContextOptions

Fornece uma opção para preservar dados de contexto de qualquer tipo, inalterados, para utilização numa chamada de retorno.

callback

(result: Office.AsyncResult<void>) => void

Opcional. Uma função que é invocada quando o registo do processador é devolvido, cujo único parâmetro é do tipo Office.AsyncResult.

Retornos

void

Comentários

Conjunto de requisitos: DialogAPI 1.2

Pode adicionar vários processadores de eventos para o tipo de evento especificado, desde que o nome de cada função de processador de eventos seja exclusivo.

addHandlerAsync(eventType, handler, callback)

Adiciona um processador de eventos ao objeto com o tipo de evento especificado.

addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, callback?: (result: AsyncResult<void>) => void): void;

Parâmetros

eventType
Office.EventType

Especifica o tipo de evento a ser adicionado. Tem de ser Office.EventType.DialogParentMessageReceived.

handler

(result: Office.DialogParentMessageReceivedEventArgs) => void

A função de processador de eventos a adicionar, cujo único parâmetro é do tipo Office.DialogParentMessageReceivedEventArgs.

callback

(result: Office.AsyncResult<void>) => void

Opcional. Uma função que é invocada quando o registo do processador é devolvido, cujo único parâmetro é do tipo Office.AsyncResult.

Retornos

void

Comentários

Conjunto de requisitos: DialogAPI 1.2

Pode adicionar vários processadores de eventos para o tipo de evento especificado, desde que o nome de cada função de processador de eventos seja exclusivo.

Exemplos

// The following example shows how to add an event handler for the DialogParentMessageReceived event.
Office.onReady(() => {
    Office.context.ui.addHandlerAsync(
        Office.EventType.DialogParentMessageReceived,
        onMessageFromParent,
        onRegisterMessageComplete
    );
});

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

function onRegisterMessageComplete(asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
    }
}

closeContainer()

Fecha o contêiner de interface de usuário onde o JavaScript está sendo executado.

closeContainer(): void;

Retornos

void

Comentários

Aplicações: Excel, Outlook (Conjunto de requisitos mínimos: Caixa de Correio 1.5), PowerPoint Word

Conjuntos de requisitos:

O comportamento deste método é especificado pelo seguinte:

  • Chamado a partir de um botão de comando sem IU: Sem efeito. Qualquer caixa de diálogo aberta por displayDialogAsync permanecerá aberta.

  • Chamado a partir de um painel de tarefas: o painel de tarefas será fechado. Qualquer caixa de diálogo aberta por displayDialogAsync também será fechada. Se o painel de tarefas suportar a afixação e tiver sido afixado pelo utilizador, este não será afixado.

  • Chamada a partir de uma extensão de módulo: Sem efeito.

Exemplos

// The following example shows how to open a browser window to a download page and then close the add-in task pane.
Office.context.ui.openBrowserWindow("https://www.contoso.com/download");
Office.context.ui.closeContainer();

displayDialogAsync(startAddress, options, callback)

Apresenta uma caixa de diálogo para mostrar ou recolher informações do utilizador ou para facilitar a navegação na Web.

displayDialogAsync(startAddress: string, options?: DialogOptions, callback?: (result: AsyncResult<Dialog>) => void): void;

Parâmetros

startAddress

string

Aceita o URL https completo inicial que é aberto na caixa de diálogo. Os URLs relativos não devem ser utilizados.

options
Office.DialogOptions

Opcional. Aceita um objeto Office.DialogOptions para definir a apresentação da caixa de diálogo.

callback

(result: Office.AsyncResult<Office.Dialog>) => void

Opcional. Aceita uma função de chamada de retorno para processar a tentativa de criação da caixa de diálogo. Se for bem-sucedido, o valor AsyncResult.é um objeto caixa de diálogo.

Retornos

void

Comentários

Aplicações: Excel, Outlook, PowerPoint Word

Conjuntos de requisitos:

Este método está disponível no conjunto de requisitos de DialogApi para o Excel, PowerPoint ou Word suplementos e no requisito caixa de correio definido como 1.4 para o Outlook. Para obter mais informações sobre como especificar um conjunto de requisitos no seu manifesto, consulte Especificar as aplicações do Office e os requisitos da API, se estiver a utilizar o manifesto apenas de suplemento. Se estiver a utilizar o manifesto unificado do Microsoft 365, consulte Suplementos do Office com o manifesto de aplicação unificada para o Microsoft 365.

Importante:

  • A página inicial tem de estar no mesmo domínio que a página principal (o parâmetro startAddress). Depois que a página inicial for carregada, você poderá ir para outros domínios.

  • Qualquer chamada de Office.context.ui.messageParent página também tem de estar no mesmo domínio que a página principal.

  • Para saber mais sobre regras, limitações e melhores práticas para a API de Caixa de Diálogo do Office, consulte Melhores práticas e regras para a API de caixa de diálogo do Office.

  • Para obter informações sobre erros e como lidar com os mesmos, consulte Processar erros e eventos na caixa de diálogo do Office.

  • 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. A window.name propriedade é utilizada por estes clientes do Outlook para manter a funcionalidade entre redirecionamentos de página.

  • Na função de chamada de retorno transmitida ao método displayDialogAsync, pode utilizar as propriedades do objeto AsyncResult para devolver as seguintes informações.

Propriedade Usar
AsyncResult.value Acessar o objeto Diálogo.
AsyncResult.status Determinar o sucesso ou falha da operação.
AsyncResult.error Acessar um objeto Error que fornecerá informações de erro se a operação tiver falhado.
AsyncResult.asyncContext Acessar o objeto ou valor definido pelo usuário se você passou um como o parâmetro asyncContext.

Exemplos

// The following example shows how to open a dialog with a specified size. It also shows
// how to register a function to handle the message when Office.UI.messageParent() is called
// in the dialog. The implementation of the processMessage() function is omitted.

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);
        });
    }
);

// The following example does the same thing in TypeScript.

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

displayDialogAsync(startAddress, callback)

Apresenta uma caixa de diálogo para mostrar ou recolher informações do utilizador ou para facilitar a navegação na Web.

displayDialogAsync(startAddress: string, callback?: (result: AsyncResult<Dialog>) => void): void;

Parâmetros

startAddress

string

Aceita o URL https completo inicial que é aberto na caixa de diálogo. Os URLs relativos não devem ser utilizados.

callback

(result: Office.AsyncResult<Office.Dialog>) => void

Opcional. Aceita uma função de chamada de retorno para processar a tentativa de criação da caixa de diálogo. Se for bem-sucedido, o valor AsyncResult.é um objeto caixa de diálogo.

Retornos

void

Comentários

Aplicações: Excel, Outlook, PowerPoint Word

Conjuntos de requisitos:

Este método está disponível no conjunto de requisitos de DialogApi para o Excel, PowerPoint ou Word suplementos e no requisito caixa de correio definido como 1.4 para o Outlook. Para obter mais informações sobre como especificar um conjunto de requisitos no seu manifesto, consulte Especificar as aplicações do Office e os requisitos da API, se estiver a utilizar o manifesto apenas de suplemento. Se estiver a utilizar o manifesto unificado do Microsoft 365, consulte Suplementos do Office com o manifesto de aplicação unificada para o Microsoft 365.

Importante:

  • A página inicial tem de estar no mesmo domínio que a página principal (o parâmetro startAddress). Depois que a página inicial for carregada, você poderá ir para outros domínios.

  • Qualquer chamada de Office.context.ui.messageParent página também tem de estar no mesmo domínio que a página principal.

  • Para saber mais sobre regras, limitações e melhores práticas para a API de Caixa de Diálogo do Office, consulte Melhores práticas e regras para a API de caixa de diálogo do Office.

  • Para obter informações sobre erros e como lidar com os mesmos, consulte Processar erros e eventos na caixa de diálogo do Office.

  • 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. A window.name propriedade é utilizada por estes clientes do Outlook para manter a funcionalidade entre redirecionamentos de página.

  • Na função de chamada de retorno transmitida ao método displayDialogAsync, pode utilizar as propriedades do objeto AsyncResult para devolver as seguintes informações.

Propriedade Usar
AsyncResult.value Acessar o objeto Diálogo.
AsyncResult.status Determinar o sucesso ou falha da operação.
AsyncResult.error Acessar um objeto Error que fornecerá informações de erro se a operação tiver falhado.
AsyncResult.asyncContext Acessar o objeto ou valor definido pelo usuário se você passou um como o parâmetro asyncContext.

messageParent(message, messageOptions)

Fornece uma mensagem da caixa de diálogo a sua página pai/de abertura.

messageParent(message: string, messageOptions?: DialogMessageOptions): void;

Parâmetros

message

string

Aceita uma mensagem da caixa de diálogo para entregar para o suplemento. Qualquer coisa que possa ser serializada para uma cadeia, incluindo JSON e XML, pode ser enviada.

messageOptions
Office.DialogMessageOptions

Opcional. Fornece opções para como enviar a mensagem.

Retornos

void

Comentários

Aplicações: Excel, Outlook, PowerPoint Word

Conjuntos de requisitos:

Exemplos

// The following example shows how to send a JSON string to the parent. The profile object
// is returned from some website when a user signs into it.
function userProfileSignedIn(profile) {
    const profileMessage = {
        "name": profile.name,
        "email": profile.email,
    };
    Office.context.ui.messageParent(JSON.stringify(profileMessage));
}

openBrowserWindow(url)

Abre uma janela do browser e carrega o URL especificado.

openBrowserWindow(url: string): void;

Parâmetros

url

string

O URL completo a abrir, incluindo o protocolo (http ou https) e o número da porta, se existir. Outros protocolos, como mailto, não são suportados.

Retornos

void

Comentários

Conjunto de requisitos: OpenBrowserWindowAPI 1.1

Exemplos

// The following example shows how to open a browser window to a download page and then close the add-in task pane.
Office.context.ui.openBrowserWindow("https://www.contoso.com/download");
Office.context.ui.closeContainer();