Office.UI interface

Referencia

Paquete:: office

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

Para obtener instrucciones sobre cómo configurar cuadros de diálogo, vea Usar la API de cuadros de diálogo en los complementos de Office.

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.

Importante:

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.
Para obtener información sobre las reglas, las limitaciones y los procedimientos recomendados para la API de cuadro de diálogo de Office, consulte Procedimientos recomendados y reglas para la API de diálogo de Office.
Para obtener información sobre los errores y cómo controlarlos, vea Controlar errores y eventos en el cuadro de diálogo de Office.
En Outlook en la Web y nueva Outlook en Windows, no establezca la propiedad window.name al configurar un cuadro de diálogo en el complemento. Estos window.name clientes de Outlook usan la propiedad para mantener la funcionalidad entre los redireccionamientos de página.
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:

Importante:

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.
Para obtener información sobre las reglas, las limitaciones y los procedimientos recomendados para la API de cuadro de diálogo de Office, consulte Procedimientos recomendados y reglas para la API de diálogo de Office.
Para obtener información sobre los errores y cómo controlarlos, vea Controlar errores y eventos en el cuadro de diálogo de Office.
En Outlook en la Web y nueva Outlook en Windows, no establezca la propiedad window.name al configurar un cuadro de diálogo en el complemento. Estos window.name clientes de Outlook usan la propiedad para mantener la funcionalidad entre los redireccionamientos de página.
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 (http o https) y el número de puerto, si existe. No se admiten otros protocolos como mailto.

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