Office.UI interface

Referencia

Paquete:: office

Proporciona objetos y métodos que puede usar para crear y manipular componentes de interfaz de usuario, como cuadros de diálogo, en los complementos de Office.

Visite "Use the Dialog API in your Office Add-ins" (Usar la API de diálogo en los complementos de Office) para obtener más información.

Comentarios

Ejemplos

// 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)	Agrega un controlador de eventos al objeto mediante el tipo de evento especificado.
addHandlerAsync(eventType, handler, callback)	Agrega un controlador de eventos al objeto mediante el tipo de evento especificado.
closeContainer()	Cierra el contenedor de la interfaz de usuario donde se ejecuta JavaScript.
displayDialogAsync(startAddress, options, callback)	Muestra un cuadro de diálogo para mostrar o recopilar información del usuario o para facilitar la navegación web.
displayDialogAsync(startAddress, callback)	Muestra un cuadro de diálogo para mostrar o recopilar información del usuario o para facilitar la navegación web.
messageParent(message, messageOptions)	Entrega un mensaje desde el cuadro de diálogo a su pagina primaria o de apertura.
openBrowserWindow(url)	Abre una ventana del explorador y carga la dirección URL especificada.

Detalles del método

addHandlerAsync(eventType, handler, options, callback)

Agrega un controlador de eventos al objeto mediante el 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 el tipo de evento que se debe agregar. Debe ser Office.EventType.DialogParentMessageReceived.

handler: (result: Office.DialogParentMessageReceivedEventArgs) => void

Función del controlador de eventos que se va a agregar, cuyo único parámetro es de tipo Office.DialogParentMessageReceivedEventArgs.

options: Office.AsyncContextOptions

Proporciona una opción para conservar los datos de contexto de cualquier tipo, sin cambios, para su uso en una devolución de llamada.

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

Opcional. Función que se invoca cuando se devuelve el registro del controlador, cuyo único parámetro es de tipo Office.AsyncResult.

Devoluciones

void

Comentarios

Conjunto de requisitos: DialogAPI 1.2

Puede agregar varios controladores de eventos para el tipo de evento especificado siempre y cuando el nombre de cada función de controlador de eventos sea único.

addHandlerAsync(eventType, handler, callback)

Agrega un controlador de eventos al objeto mediante el tipo de evento especificado.

addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, callback?: (result: AsyncResult<void>) => void): void;

Parámetros

eventType: Office.EventType

Especifica el tipo de evento que se debe agregar. Debe ser Office.EventType.DialogParentMessageReceived.

handler: (result: Office.DialogParentMessageReceivedEventArgs) => void

Función del controlador de eventos que se va a agregar, cuyo único parámetro es de tipo Office.DialogParentMessageReceivedEventArgs.

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

Opcional. Función que se invoca cuando se devuelve el registro del controlador, cuyo único parámetro es de tipo Office.AsyncResult.

Devoluciones

void

Comentarios

Conjunto de requisitos: DialogAPI 1.2

Puede agregar varios controladores de eventos para el tipo de evento especificado siempre y cuando el nombre de cada función de controlador de eventos sea único.

Ejemplos

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

Cierra el contenedor de la interfaz de usuario donde se ejecuta JavaScript.

closeContainer(): void;

Devoluciones

void

Comentarios

Aplicaciones: Excel, Outlook (conjunto de requisitos mínimos: Buzón 1.5), PowerPoint, Word

Conjuntos de requisitos:

El comportamiento de este método se especifica mediante lo siguiente:

Se llama desde un botón de comando sin interfaz de usuario: sin efecto. No permanecerá abierto ningún cuadro de diálogo que se haya abierto mediante displayDialogAsync.
Llamada desde un panel de tareas: se cerrará el panel de tareas. Cualquier cuadro de diálogo abierto por displayDialogAsync también se cerrará. Si el panel de tareas admite el anclaje y el usuario lo ancló, se desanclará.
Se llama desde una extensión de módulo: sin efecto.

Ejemplos

// 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)

Muestra un cuadro de diálogo para mostrar o recopilar información del usuario o para facilitar la navegación web.

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

Parámetros

startAddress: string

Acepta la dirección URL HTTPS completa inicial que se abre en el cuadro de diálogo. No se deben usar direcciones URL relativas.

options: Office.DialogOptions

Opcional. Acepta un objeto Office.DialogOptions para definir la visualización del cuadro de diálogo.

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

Opcional. Acepta una función de devolución de llamada para controlar el intento de creación del cuadro de diálogo. Si se ejecuta correctamente, AsyncResult.value es un objeto Dialog.

Devoluciones

void

Comentarios

Aplicaciones: Excel, Outlook, PowerPoint, Word

Conjuntos de requisitos:

Este método está disponible en el conjunto de requisitos DialogApi para complementos de Excel, PowerPoint o Word y en el conjunto de requisitos de buzón 1.4 para Outlook. Para obtener más información sobre cómo especificar un conjunto de requisitos en el manifiesto, vea Especificar aplicaciones de Office y requisitos de API, si usa el manifiesto de solo complemento. Si usa el manifiesto unificado para Microsoft 365, consulte Complementos de Office con el manifiesto de aplicación unificada para Microsoft 365.

La página inicial debe estar en el mismo dominio que la página primaria (el parámetro startAddress). Después de cargar la página inicial, puede ir a otros dominios.

Cualquier llamada a Office.context.ui.messageParent página también debe estar en el mismo dominio que la página primaria.

Consideraciones de diseño:

Las siguientes consideraciones de diseño se aplican a los cuadros de diálogo.

Un panel de tareas de complemento de Office solo puede tener un cuadro de diálogo abierto en cualquier momento. Se pueden abrir varios diálogos al mismo tiempo desde Comandos de complemento (botones de cinta personalizados o elementos de menú).
El usuario puede mover y cambiar de tamaño cada cuadro de diálogo.
Cada cuadro de diálogo se centra en la pantalla cuando se abre.
Los cuadros de diálogo aparecen sobre la aplicación y en el orden en que se crearon.

Use un cuadro de diálogo para:

Mostrar páginas de autenticación para recopilar las credenciales de usuario.
Muestra una pantalla de error, progreso o entrada desde un comando ShowTaskpane o ExecuteAction.
Aumentar temporalmente el área de superficie que un usuario tiene disponible para completar una tarea.

No use un cuadro de diálogo para interactuar con un documento. En su lugar, use un panel de tareas.

Errores de displayDialogAsync

Número de código	Significado
12004	El dominio de la dirección URL pasada a displayDialogAsync no es de confianza. El dominio debe estar en el mismo dominio que la página de host (incluido el número de protocolo y de puerto), o debe registrarse en la sección `AppDomains` del manifiesto del complemento.
12005	La dirección URL pasada a displayDialogAsync usa el protocolo HTTP. Se necesita HTTPS. (En algunas versiones de Office, el mensaje de error devuelto con 12005 es el mismo devuelto para 12004).
12007	Ya hay un cuadro de diálogo abierto en el panel de tareas. Un complemento de panel de tareas solo puede tener abierto un cuadro de diálogo al mismo tiempo.
12009	El usuario ha decidido ignorar el cuadro de diálogo. Este error puede ocurrir en las versiones en línea de Office, donde los usuarios pueden elegir no permitir que un complemento presente un cuadro de diálogo.

En la función de devolución de llamada que se pasa al método displayDialogAsync, puede usar las propiedades del objeto AsyncResult para devolver la siguiente información.

Propiedad	Utilice
`AsyncResult.value`	Acceso al objeto Dialog.
`AsyncResult.status`	Determinar si la operación se ha completado correctamente o no.
`AsyncResult.error`	Tener acceso a un objeto Error que proporcione información sobre el error si la operación no se ha llevado a cabo correctamente.
`AsyncResult.asyncContext`	Acceda al objeto o valor definidos por el usuario, si ha pasado uno como parámetro asyncContext.

Ejemplos

// 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)

Muestra un cuadro de diálogo para mostrar o recopilar información del usuario o para facilitar la navegación web.

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

Parámetros

startAddress: string

Acepta la dirección URL HTTPS completa inicial que se abre en el cuadro de diálogo. No se deben usar direcciones URL relativas.

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

Opcional. Acepta una función de devolución de llamada para controlar el intento de creación del cuadro de diálogo. Si se ejecuta correctamente, AsyncResult.value es un objeto Dialog.

Devoluciones

void

Comentarios

Aplicaciones: Excel, Outlook, PowerPoint, Word

Conjuntos de requisitos:

La página inicial debe estar en el mismo dominio que la página primaria (el parámetro startAddress). Después de cargar la página inicial, puede ir a otros dominios.

Cualquier llamada a Office.context.ui.messageParent página también debe estar en el mismo dominio que la página primaria.

Consideraciones de diseño:

Las siguientes consideraciones de diseño se aplican a los cuadros de diálogo.

Un panel de tareas de complemento de Office solo puede tener un cuadro de diálogo abierto en cualquier momento. Se pueden abrir varios diálogos al mismo tiempo desde Comandos de complemento (botones de cinta personalizados o elementos de menú).
El usuario puede mover y cambiar de tamaño cada cuadro de diálogo.
Cada cuadro de diálogo se centra en la pantalla cuando se abre.
Los cuadros de diálogo aparecen sobre la aplicación y en el orden en que se crearon.

Use un cuadro de diálogo para:

Mostrar páginas de autenticación para recopilar las credenciales de usuario.
Muestra una pantalla de error, progreso o entrada desde un comando ShowTaskpane o ExecuteAction.
Aumentar temporalmente el área de superficie que un usuario tiene disponible para completar una tarea.

No use un cuadro de diálogo para interactuar con un documento. En su lugar, use un panel de tareas.

Errores de displayDialogAsync

Número de código	Significado
12004	El dominio de la dirección URL pasada a displayDialogAsync no es de confianza. El dominio debe estar en el mismo dominio que la página de host (incluido el número de protocolo y de puerto), o debe registrarse en la sección `AppDomains` del manifiesto del complemento.
12005	La dirección URL pasada a displayDialogAsync usa el protocolo HTTP. Se necesita HTTPS. (En algunas versiones de Office, el mensaje de error devuelto con 12005 es el mismo devuelto para 12004).
12007	Ya hay un cuadro de diálogo abierto en el panel de tareas. Un complemento de panel de tareas solo puede tener abierto un cuadro de diálogo al mismo tiempo.
12009	El usuario ha decidido ignorar el cuadro de diálogo. Este error puede ocurrir en las versiones en línea de Office, donde los usuarios pueden elegir no permitir que un complemento presente un cuadro de diálogo.

En la función de devolución de llamada que se pasa al método displayDialogAsync, puede usar las propiedades del objeto AsyncResult para devolver la siguiente información.

Propiedad	Utilice
`AsyncResult.value`	Acceso al objeto Dialog.
`AsyncResult.status`	Determinar si la operación se ha completado correctamente o no.
`AsyncResult.error`	Tener acceso a un objeto Error que proporcione información sobre el error si la operación no se ha llevado a cabo correctamente.
`AsyncResult.asyncContext`	Acceda al objeto o valor definidos por el usuario, si ha pasado uno como parámetro asyncContext.

messageParent(message, messageOptions)

Entrega un mensaje desde el cuadro de diálogo a su pagina primaria o de apertura.

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

Parámetros

message: string

Acepta un mensaje del cuadro de diálogo para entregarlo al complemento. Todo lo que se puede serializar en una cadena, incluidos JSON y XML, se puede enviar.

messageOptions: Office.DialogMessageOptions

Opcional. Proporciona opciones para enviar el mensaje.

Devoluciones

void

Comentarios

Aplicaciones: Excel, Outlook, PowerPoint, Word

Conjuntos de requisitos:

DialogAPI
Mailbox 1.4
Si se usa el messageOptions parámetro , también se requiere DialogOrigin 1.1 .

Ejemplos

// 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 una ventana del explorador y carga la dirección URL especificada.

openBrowserWindow(url: string): void;

Parámetros

url: string

La dirección URL completa que se va a abrir, incluido el protocolo (por ejemplo, https) y el número de puerto, si existe.

Devoluciones

void

Comentarios

Conjunto de requisitos: OpenBrowserWindowAPI 1.1

Ejemplos

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

Compartir a través de

Office.UI interface

Comentarios

Ejemplos

Métodos

Detalles del método

addHandlerAsync(eventType, handler, options, callback)

Parámetros

Devoluciones

Comentarios

addHandlerAsync(eventType, handler, callback)

Parámetros

Devoluciones

Comentarios

Ejemplos

closeContainer()

Devoluciones

Comentarios

Ejemplos

displayDialogAsync(startAddress, options, callback)

Parámetros

Devoluciones

Comentarios

Ejemplos

displayDialogAsync(startAddress, callback)

Parámetros

Devoluciones

Comentarios

messageParent(message, messageOptions)

Parámetros

Devoluciones

Comentarios

Ejemplos

openBrowserWindow(url)

Parámetros

Devoluciones

Comentarios

Ejemplos

Recursos adicionales