Office.UI interface
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.
Métodos
| add |
Agrega un controlador de eventos al objeto mediante el tipo de evento especificado. |
| add |
Agrega un controlador de eventos al objeto mediante el tipo de evento especificado. |
| close |
Cierra el contenedor de la interfaz de usuario donde se ejecuta JavaScript. |
| display |
Muestra un cuadro de diálogo para mostrar o recopilar información del usuario o para facilitar la navegación web. |
| display |
Muestra un cuadro de diálogo para mostrar o recopilar información del usuario o para facilitar la navegación web. |
| message |
Entrega un mensaje desde el cuadro de diálogo a su pagina primaria o de apertura. |
| open |
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.
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 XML. Si usa el manifiesto de Teams (versión preliminar), consulte Manifiesto de Teams para complementos de Office (versión preliminar).
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 | Determinación del éxito o error de la operación |
AsyncResult.error | Acceso a un objeto Error que proporciona información de error si se produjo un error en la operación |
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:
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 XML. Si usa el manifiesto de Teams (versión preliminar), consulte Manifiesto de Teams para complementos de Office (versión preliminar).
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 | Determinación del éxito o error de la operación |
AsyncResult.error | Acceso a un objeto Error que proporciona información de error si se produjo un error en la operación |
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
Conjuntos de requisitos:
Si se usa el
messageOptionspará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
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de