Office.UI interface
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
add |
Adiciona um processador de eventos ao objeto com o tipo de evento especificado. |
add |
Adiciona um processador de eventos ao objeto com o tipo de evento especificado. |
close |
Fecha o contêiner de interface de usuário onde o JavaScript está sendo executado. |
display |
Apresenta uma caixa de diálogo para mostrar ou recolher informações do utilizador ou para facilitar a navegação na Web. |
display |
Apresenta uma caixa de diálogo para mostrar ou recolher informações do utilizador ou para facilitar a navegação na Web. |
message |
Fornece uma mensagem da caixa de diálogo a sua página pai/de abertura. |
open |
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:
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 (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();