Office.UI interface

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

Retornos

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.

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

Retornos

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

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

closeContainer(): void;

Retornos

Comentários

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

Conjuntos de requisitos:

• DialogAPI

• Caixa de correio 1.5

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

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

Retornos

Comentários

Aplicações: Excel, Outlook, PowerPoint Word

Conjuntos de requisitos:

• DialogAPI

• Caixa de correio 1.4

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.

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.

Considerações de design:

As seguintes considerações de design aplicam-se às caixas de diálogo.

• Um painel de tarefas do Suplemento do Office só pode ter uma caixa de diálogo aberta em qualquer altura. Várias caixas de diálogo podem ser abertas ao mesmo tempo a partir de Comandos de Suplementos (botões do friso personalizados ou itens de menu).

• Todas as caixas de diálogo podem ser movidas e redimensionadas pelo usuário.

• Todas as caixas de diálogo são centralizadas na tela quando abertas.

• As caixas de diálogo são apresentadas na parte superior da aplicação e pela ordem em que foram criadas.

Usar uma caixa de diálogo para:

• Exibir páginas de autenticação para coletar credenciais de usuário.

• Apresentar um ecrã de erro/progresso/entrada a partir de um comando ShowTaskpane ou ExecuteAction.

• Aumentar temporariamente a área de superfície de que um usuário dispõe para concluir uma tarefa.

Não use uma caixa de diálogo para interagir com um documento. Use um painel de tarefas em vez disso.

erros displayDialogAsync

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.

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

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

Retornos

Comentários

Aplicações: Excel, Outlook, PowerPoint Word

Conjuntos de requisitos:

• DialogAPI

• Caixa de correio 1.4

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.

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.

Considerações de design:

As seguintes considerações de design aplicam-se às caixas de diálogo.

• Um painel de tarefas do Suplemento do Office só pode ter uma caixa de diálogo aberta em qualquer altura. Várias caixas de diálogo podem ser abertas ao mesmo tempo a partir de Comandos de Suplementos (botões do friso personalizados ou itens de menu).

• Todas as caixas de diálogo podem ser movidas e redimensionadas pelo usuário.

• Todas as caixas de diálogo são centralizadas na tela quando abertas.

• As caixas de diálogo são apresentadas na parte superior da aplicação e pela ordem em que foram criadas.

Usar uma caixa de diálogo para:

• Exibir páginas de autenticação para coletar credenciais de usuário.

• Apresentar um ecrã de erro/progresso/entrada a partir de um comando ShowTaskpane ou ExecuteAction.

• Aumentar temporariamente a área de superfície de que um usuário dispõe para concluir uma tarefa.

Não use uma caixa de diálogo para interagir com um documento. Use um painel de tarefas em vez disso.

erros displayDialogAsync

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.

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

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

Parâmetros

Retornos

Comentários

Aplicações: Excel, Outlook, PowerPoint Word

Conjuntos de requisitos:

• DialogAPI

• Caixa de correio 1.4

• Se o messageOptions parâmetro for utilizado, o DialogOrigin 1.1 também é necessário.

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

Abre uma janela do browser e carrega o URL especificado.

openBrowserWindow(url: string): void;

Parâmetros

Retornos

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