Office.UI interface

Referência

Pacote:: office

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

Visite "Utilizar a API de Caixa de Diálogo nos seus Suplementos do Office" para obter mais informações.

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.

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

Número do código	Significado
12004	O domínio do URL transmitido para displayDialogAsync não é fidedigno. O domínio deve ser o mesmo domínio da página de host (incluindo o protocolo e o número da porta) ou deve ser registrado na seção `AppDomains` do manifesto do suplemento.
12005	O URL transmitido para apresentarDialogAsync utiliza o protocolo HTTP. HTTPS é necessário. (Em algumas versões do Office, a mensagem de erro retornada com 12005 é a mesma retornada para 12004.)
12007	Uma caixa de diálogo já está aberta no painel de tarefas. Um suplemento de painel só pode abrir uma caixa de diálogo por vez.
12009	O usuário opta por ignorar a caixa de diálogo. Este erro pode ocorrer em versões online do Office, em que os usuários podem optar por não permitir que um suplemento apresente uma caixa de diálogo.

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:

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

Número do código	Significado
12004	O domínio do URL transmitido para displayDialogAsync não é fidedigno. O domínio deve ser o mesmo domínio da página de host (incluindo o protocolo e o número da porta) ou deve ser registrado na seção `AppDomains` do manifesto do suplemento.
12005	O URL transmitido para apresentarDialogAsync utiliza o protocolo HTTP. HTTPS é necessário. (Em algumas versões do Office, a mensagem de erro retornada com 12005 é a mesma retornada para 12004.)
12007	Uma caixa de diálogo já está aberta no painel de tarefas. Um suplemento de painel só pode abrir uma caixa de diálogo por vez.
12009	O usuário opta por ignorar a caixa de diálogo. Este erro pode ocorrer em versões online do Office, em que os usuários podem optar por não permitir que um suplemento apresente uma caixa de diálogo.

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:

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

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 (por exemplo, https) e o número da porta, se existir.

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

Compartilhar via

Office.UI interface

Comentários

Exemplos

Métodos

Detalhes do método

addHandlerAsync(eventType, handler, options, callback)

Parâmetros

Retornos

Comentários

addHandlerAsync(eventType, handler, callback)

Parâmetros

Retornos

Comentários

Exemplos

closeContainer()

Retornos

Comentários

Exemplos

displayDialogAsync(startAddress, options, callback)

Parâmetros

Retornos

Comentários

Exemplos

displayDialogAsync(startAddress, callback)

Parâmetros

Retornos

Comentários

messageParent(message, messageOptions)

Parâmetros

Retornos

Comentários

Exemplos

openBrowserWindow(url)

Parâmetros

Retornos

Comentários

Exemplos

Recursos adicionais