Office.UI interface
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.
// 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 });
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. |
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.
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;
}
}
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();
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);
});
}
);
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.
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. |
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));
}
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();
Comentários do Office Add-ins
O Office Add-ins é um projeto código aberto. Selecione um link para fornecer comentários: