Office.UI interface

Pacote:

office

Fornece objetos e métodos que você pode usar para criar e manipular componentes da interface do usuário, como caixas de diálogo, em seus Suplementos do Office.

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

Métodos

addHandlerAsync(eventType, handler, options, callback)	Adiciona um manipulador de eventos ao objeto usando o tipo de evento especificado.
addHandlerAsync(eventType, handler, callback)	Adiciona um manipulador de eventos ao objeto usando 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)	Exibe uma caixa de diálogo para mostrar ou coletar informações do usuário ou para facilitar a navegação na Web.
displayDialogAsync(startAddress, callback)	Exibe uma caixa de diálogo para mostrar ou coletar informações do usuário 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 navegador e carrega a URL especificada.

Detalhes do método

addHandlerAsync(eventType, handler, options, callback)

Adiciona um manipulador de eventos ao objeto usando 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. Isso deve ser Office.EventType.DialogParentMessageReceived.

handler

(result: Office.DialogParentMessageReceivedEventArgs) => void

A função do manipulador de eventos a ser adicionada, 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 uso em um retorno de chamada.

callback

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

Opcional. Uma função que é invocada quando o registro do manipulador retorna, cujo único parâmetro é do tipo Office.AsyncResult.

Retornos

void

Comentários

Conjunto de requisitos: DialogAPI 1.2

Você pode adicionar vários manipuladores de eventos para o tipo de evento especificado, desde que o nome de cada função do manipulador de eventos seja exclusivo.

addHandlerAsync(eventType, handler, callback)

Adiciona um manipulador de eventos ao objeto usando 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. Isso deve ser Office.EventType.DialogParentMessageReceived.

handler

(result: Office.DialogParentMessageReceivedEventArgs) => void

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

callback

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

Opcional. Uma função que é invocada quando o registro do manipulador retorna, cujo único parâmetro é do tipo Office.AsyncResult.

Retornos

void

Comentários

Conjunto de requisitos: DialogAPI 1.2

Você pode adicionar vários manipuladores de eventos para o tipo de evento especificado, desde que o nome de cada função do manipulador 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

Aplicativos: 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 desse método é especificado pelo seguinte:

• Chamado de um botão de comando sem interface do usuário: sem efeito. Qualquer caixa de diálogo aberta por displayDialogAsync permanecerá aberta.

• Chamado de um painel de tarefas: o painel de tarefas será fechado. Qualquer caixa de diálogo aberta pelo displayDialogAsync também será fechada. Se o painel de tarefas der suporte à fixação e tiver sido fixado pelo usuário, ele não será fixado.

• Chamado de uma extensão de módulo: sem efeito.

displayDialogAsync(startAddress, options, callback)

Exibe uma caixa de diálogo para mostrar ou coletar informações do usuário ou para facilitar a navegação na Web.

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

Parâmetros

startAddress

string

Aceita a URL HTTPS completa inicial que é aberta na caixa de diálogo. URLs relativas não devem ser usadas.

options

Office.DialogOptions

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

callback

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

Opcional. Aceita uma função de retorno de chamada para lidar com a tentativa de criação da caixa de diálogo. Se for bem-sucedido, o AsyncResult.value será um objeto Dialog.

Retornos

void

Comentários

Aplicativos: Excel, Outlook, PowerPoint, Word

Conjuntos de requisitos:

• DialogAPI

• Caixa de correio 1.4

Esse método está disponível no conjunto de requisitos dialogApi para suplementos do Excel, PowerPoint ou Word e no conjunto de requisitos da caixa de correio 1.4 para Outlook. Para saber mais sobre como especificar um requisito definido em seu manifesto, consulte Especificar aplicativos do Office e requisitos de API, se você estiver usando o manifesto XML. Se você estiver usando o manifesto do Teams (versão prévia), consulte o manifesto do Teams para Suplementos do Office (versão prévia).

A página inicial deve estar no mesmo domínio que a página pai (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 deve estar no mesmo domínio que a página pai.

Considerações de design:

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

• Um painel de tarefas do Suplemento do Office pode ter apenas uma caixa de diálogo aberta a qualquer momento. Várias caixas de diálogo podem ser abertas ao mesmo tempo em Comandos de Suplemento (botões de faixa de opções 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 aparecem na parte superior do aplicativo e na ordem em que foram criadas.

Usar uma caixa de diálogo para:

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

• Exiba uma tela de erro/progresso/entrada 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 da URL passado para exibirDialogAsync não é confiável. 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	A URL passada para exibirDialogAsync usa 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 retorno de chamada passada para o método displayDialogAsync, você pode usar as propriedades do objeto AsyncResult para retornar as informações a seguir.

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)

Exibe uma caixa de diálogo para mostrar ou coletar informações do usuário ou para facilitar a navegação na Web.

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

Parâmetros

startAddress

string

Aceita a URL HTTPS completa inicial que é aberta na caixa de diálogo. URLs relativas não devem ser usadas.

callback

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

Opcional. Aceita uma função de retorno de chamada para lidar com a tentativa de criação da caixa de diálogo. Se for bem-sucedido, o AsyncResult.value será um objeto Dialog.

Retornos

void

Comentários

Aplicativos: Excel, Outlook, PowerPoint, Word

Conjuntos de requisitos:

• DialogAPI

• Caixa de correio 1.4

Esse método está disponível no conjunto de requisitos dialogApi para suplementos do Excel, PowerPoint ou Word e no conjunto de requisitos da caixa de correio 1.4 para Outlook. Para saber mais sobre como especificar um requisito definido em seu manifesto, consulte Especificar aplicativos do Office e requisitos de API, se você estiver usando o manifesto XML. Se você estiver usando o manifesto do Teams (versão prévia), consulte o manifesto do Teams para Suplementos do Office (versão prévia).

A página inicial deve estar no mesmo domínio que a página pai (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 deve estar no mesmo domínio que a página pai.

Considerações de design:

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

• Um painel de tarefas do Suplemento do Office pode ter apenas uma caixa de diálogo aberta a qualquer momento. Várias caixas de diálogo podem ser abertas ao mesmo tempo em Comandos de Suplemento (botões de faixa de opções 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 aparecem na parte superior do aplicativo e na ordem em que foram criadas.

Usar uma caixa de diálogo para:

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

• Exiba uma tela de erro/progresso/entrada 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 da URL passado para exibirDialogAsync não é confiável. 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	A URL passada para exibirDialogAsync usa 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 retorno de chamada passada para o método displayDialogAsync, você pode usar as propriedades do objeto AsyncResult para retornar as informações a seguir.

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 de caracteres, incluindo JSON e XML, pode ser enviada.

messageOptions

Office.DialogMessageOptions

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

Retornos

void

Comentários

Conjuntos de requisitos:

• DialogAPI

• Se o messageOptions parâmetro for usado, o DialogOrigin 1.1 também será 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 navegador e carrega a URL especificada.

openBrowserWindow(url: string): void;

Parâmetros

url

string

A URL completa a ser aberta incluindo o protocolo (por exemplo, https) e o número da porta, se houver.

Retornos

void

Comentários

Conjunto de requisitos: OpenBrowserWindowAPI 1.1