Modelo de objetos de API de JavaScript común

Artículo
03/21/2023

Importante

Este artículo se aplica a las API comunes, el modelo de API de JavaScript de Office que se introdujo con Office 2013. Estas API incluyen características como la interfaz de usuario, los cuadros de diálogo y la configuración del cliente, que son comunes a varios tipos de aplicaciones de Office. Los complementos de Outlook usan exclusivamente API comunes, especialmente los subconjuntos de API que se exponen a través del objeto Buzón.

Solo debe usar las API comunes para escenarios que no son compatibles con las API específicas de aplicaciones. Para saber cuándo usar las API comunes en lugar de las API específicas de la aplicación, consulte Comprender la API de JavaScript de Office.

Las API de JavaScript de Office proporcionan acceso a la funcionalidad subyacente de la aplicación cliente de Office. La mayor parte de este acceso pasa a través de algunos objetos importantes. El objeto Context da acceso al entorno de tiempo de ejecución después de la inicialización. El objeto Document da al usuario el control sobre un documento de Word, Excel o PowerPoint. El objeto Mailbox proporciona a un complemento de Outlook acceso a mensajes, citas y perfiles de usuario. Comprender las relaciones entre estos objetos de alto nivel es la base de un complemento de Office.

Objeto Context

Se aplica a: todos los tipos de complementos

Cuando se inicializa un complemento, tiene muchos objetos diferentes con los que puede interactuar en el entorno de tiempo de ejecución. El contexto de tiempo de ejecución del complemento se refleja en la API mediante el objeto Context. El objeto Context es el objeto principal que proporciona acceso a los objetos más importantes de la API, como los objetos Document y Mailbox, que a su vez ofrecen acceso al contenido del documento y el buzón.

Por ejemplo, en complementos de contenido o de panel de tareas, se puede usar la propiedad document del objeto Context para obtener acceso a las propiedades y los métodos del objeto Document e interactuar con el contenido de documentos de Word, hojas de cálculo de Excel o programaciones de Project. Del mismo modo, en los complementos de Outlook se puede usar la propiedad mailbox del objeto Context para obtener acceso a las propiedades y los métodos del objeto Mailbox e interactuar con el contenido de mensajes, convocatorias de reunión o citas.

El objeto Context también proporciona acceso a las propiedades contentLanguage y displayLanguage que permiten determinar la configuración regional (idioma) usada en el documento o elemento, o por la aplicación de Office. La propiedad roamingSettings permite el acceso a los miembros del objeto RoamingSettings, que almacena la configuración específica para el complemento de los buzones de usuarios individuales. Por último, el objeto Context proporciona una propiedad ui que permite al complemento iniciar cuadros de diálogo emergentes.

Objeto Document

Se aplica a: tipos de complementos de panel de tareas y de contenido

Para interactuar con los datos de un documento en Excel, PowerPoint y Word, la API ofrece el objeto Document. Puede usar Document miembros de objeto para acceder a los datos de las siguientes maneras.

Leer y escribir en selecciones activas en forma de texto, celdas contiguas (matrices) o tablas.
Datos tabulares (tablas o matrices).
Enlaces (creados con los métodos "add" del Bindings objeto ).
Elementos XML personalizados (solo para Word).
Configuraciones o estados de complemento conservados para cada complemento en el documento.

También puede usar el Document objeto para interactuar con datos en documentos de Project. La funcionalidad específica de Project de la API se documenta en la clase abstracta de ProjectDocument de los miembros. Para más información sobre cómo crear complementos de panel de tareas para Project, vea Complementos de panel de tareas para Project.

Todas estas formas de acceso a datos comienzan desde una instancia del objeto abstracto Document .

Puede tener acceso a una instancia del Document objeto cuando se inicializa el panel de tareas o el complemento de contenido mediante la propiedad document del Context objeto . El Document objeto define métodos comunes de acceso a datos compartidos entre documentos de Word y Excel, y también proporciona acceso al CustomXmlParts objeto para documentos de Word.

El Document objeto admite cuatro formas para que los desarrolladores accedan al contenido del documento.

Acceso basado en la selección
Acceso basado en el enlace
Acceso basado en elementos XML personalizados (solo en Word)
Acceso basado en documentos completos (solo en PowerPoint y Word)

Para explicar mejor cómo funcionan los métodos de acceso a datos basados en la selección y el enlace, antes explicaremos de qué manera las API de acceso a datos proporcionan acceso a datos coherentes entre las distintas aplicaciones de Office.

Acceso a datos coherentes entre las aplicaciones de Office

Se aplica a: tipos de complementos de panel de tareas y de contenido

Para crear extensiones que funcionen sin problemas en diferentes documentos de Office, la API de JavaScript de Office abstrae las particularidades de cada aplicación de Office a través de tipos de datos comunes y la capacidad de convertir contenido de documentos diferentes en tres tipos de datos comunes.

Tipos de datos comunes

Tanto en el acceso a datos basado en la selección como el basado en el enlace, el contenido de los documentos se expone a través de tipos de datos compartidos por todas las aplicaciones de Office compatibles. Se admiten tres tipos de datos principales.

Tipo de datos	Description	Compatibilidad con aplicación host
Texto	Proporciona una representación de cadena de los datos de la selección o del enlace.	En Excel, Project y PowerPoint, solo se admite texto sin formato. En Word, se admiten tres formatos de texto: texto sin formato, HTML y Office Open XML (OOXML). Cuando se selecciona texto en una celda de Excel, los métodos basados en selecciones leen y escriben en todo el contenido de la celda, aunque solo esté seleccionada una parte del texto en la celda. Cuando se selecciona texto en Word y PowerPoint, los métodos basados en selecciones leen y escriben solo la secuencia de caracteres seleccionada. Project y PowerPoint solo admiten el acceso a datos basados en selección.
Matriz	Proporciona los datos de la selección o del enlace como una Array bidimensional, implementada en JavaScript como una matriz de matrices. Por ejemplo, dos líneas de valores de string en dos columnas serían `[['a', 'b'], ['c', 'd']]` y una sola columna de tres filas sería `[['a'], ['b'], ['c']]`.	El acceso a datos de matriz solo se admite en Excel y Word.
Tabla	Proporciona los datos de la selección o del enlace como un objeto TableData. El `TableData` objeto expone los datos a través de las `headers` propiedades y `rows` .	El acceso a datos de tabla solo se admite en Excel y Word.

Coerción de tipos de datos

Los métodos de acceso a datos de losDocument objetos Binding y admiten la especificación del tipo de datos deseado mediante el parámetro coercionType de estos métodos y los valores de enumeración CoercionType correspondientes. Independientemente de la forma real del enlace, las distintas aplicaciones de Office admiten los tipos de datos comunes tal intentar convertir los datos en el tipo de datos solicitado. Por ejemplo, si se selecciona un párrafo o una tabla de Word, el desarrollador puede especificar que se lea como texto sin formato, como texto HTML, Office Open XML o como una tabla; por su parte, la implementación de la API administra las transformaciones y las conversiones de datos necesarias.

Sugerencia

¿Cuándo debería usar la matriz en vez de la tabla coercionType para el acceso a los datos? Si necesita que los datos tabulares crezcan dinámicamente cuando se agregan filas y columnas y debe trabajar con encabezados de tabla, debe usar el tipo de datos de tabla (especificando el parámetro coercionType de un método de acceso a datos de objeto Document o Binding como "table" o Office.CoercionType.Table). La adición de filas y columnas en la estructura de datos se admite tanto en los datos de matriz como de tabla, pero la anexión de filas y columnas solo se admite para los datos de tabla. Si no tiene previsto agregar filas y columnas, y los datos no requieren funcionalidad de encabezado, debe usar el tipo de datos de matriz (especificando el parámetro coercionType del método de acceso a datos como "matrix" o Office.CoercionType.Matrix), que proporciona un modelo más sencillo de interacción con los datos.

Si los datos no se pueden convertir a un tipo especificado, la propiedad AsyncResult.status en la devolución de llamada devuelve "failed". En ese caso, se puede usar la propiedad AsyncResult.error para obtener acceso al objeto Error con información sobre por qué falló la llamada del método.

Trabajar con selecciones mediante el objeto Document

El Document objeto expone métodos que permiten leer y escribir en la selección actual del usuario de forma "obtener y establecer". Para ello, el Document objeto proporciona los getSelectedDataAsync métodos y setSelectedDataAsync .

Para ver ejemplos de código que muestran cómo realizar tareas con selecciones, vea Leer y escribir datos en la selección activa de un documento u hoja de cálculo.

Trabajar con enlaces mediante los objetos Bindings y Binding

El acceso a datos basado en enlaces permite que los complementos de contenido y panel de tareas accedan de forma coherente a una región determinada de un documento o hoja de cálculo a través de un identificador asociado a un enlace. Primero, el complemento necesita establecer el enlace con una llamada a uno de los métodos que asocian una parte del documento con un identificador único: addFromPromptAsync, addFromSelectionAsync o addFromNamedItemAsync. Después de establecer el enlace, el complemento puede usar el identificador para tener acceso a los datos de la región asociada del documento o la hoja de cálculo. La creación de enlaces proporciona el siguiente valor al complemento.

Permite el acceso a estructuras de datos comunes de aplicaciones de Office compatibles como, por ejemplo, tablas, rangos o texto (secuencia de caracteres contiguos).
Permite las operaciones de lectura/escritura sin que el usuario tenga que hacer ninguna selección.
Establece una relación entre el complemento y los datos del documento. Los enlaces se conservan en el documento y es posible tener acceso a estos más adelante.

Al establecer un enlace, también puede subscribirse a eventos de cambio de datos y de selección designados en esa región en concreto del documento u hoja de cálculo. Es decir, que al complemento solo se le notifican los cambios que ocurren dentro de la región delimitada, y no los cambios generales que se den en todo el documento u hoja de cálculo.

El objeto Bindings expone un método getAllAsync que da acceso al conjunto de todos los enlaces establecidos en el documento u hoja de cálculo. Se puede acceder a un enlace individual mediante su identificador mediante el método Bindings.getBindingByIdAsync o la función Office.select . Puede establecer nuevos enlaces, así como quitar los existentes mediante uno de los métodos siguientes del Bindings objeto: addFromSelectionAsync, addFromPromptAsync, addFromNamedItemAsync o releaseByIdAsync.

Hay tres tipos diferentes de enlaces que se especifican con el parámetro bindingType al crear un enlace con los addFromSelectionAsyncmétodos o addFromPromptAsyncaddFromNamedItemAsync .

Tipo de enlace	Description	Compatibilidad con aplicación host
Enlace de texto	Enlaza con una región del documento que se puede representar como texto.	En Word, la mayoría de las selecciones contiguas son válidas, mientras que en Excel solo se puede seleccionar una celda como destino del enlace de texto. En Excel, solo se admite el texto sin formato. En Word pueden usarse tres formatos: texto sin formato, HTML y Open XML para Office.
Enlace de matriz	Enlaza con una región fija de un documento que contiene datos tabulares sin encabezados. Los datos de un enlace de matriz se escriben o leen como una matriz bidimensional, que en JavaScript se implementa como una matriz de matrices. Por ejemplo, dos filas de valores de cadena en dos columnas se pueden escribir o leer como `[['a', 'b'], ['c', 'd']]`y una sola columna de tres filas se puede escribir o leer como `[['a'], ['b'], ['c']]`.	En Excel, se puede usar cualquier selección contigua de celdas para establecer un enlace de matriz. En Word, solo las tablas admiten enlaces de matriz.
Enlace de tabla	Enlaza con una región de un documento que contiene una tabla con encabezados. Los datos de un enlace de tablas se escriben o leen como un objeto TableData. El `TableData` objeto expone los datos a través de las propiedades de encabezados y filas .	Se puede usar como base cualquier tabla de Excel o de Word para establecer un enlace de tabla. Una vez se haya establecido un enlace de tabla, cada fila o columna nueva que se agregue a la tabla se incluirá automáticamente al enlace.

Después de crear un enlace mediante uno de los tres métodos "add" del Bindings objeto, puede trabajar con los datos y propiedades del enlace mediante los métodos del objeto correspondiente: MatrixBinding, TableBinding o TextBinding. Los tres objetos heredan los métodos getDataAsync y setDataAsync del Binding objeto que permiten interactuar con los datos enlazados.

Para ver ejemplos de código que muestran cómo realizar tareas con enlaces, vea Enlazar a regiones de un documento u hoja de cálculo.

Trabajar con elementos XML personalizados mediante los objetos CustomXmlParts y CustomXmlPart

Se aplica a: complementos de panel de tareas para Word

Los objetos CustomXmlParts y CustomXmlPart de la API proporcionan acceso a elementos XML personalizados en documentos de Word, que permiten la manipulación controlada por XML de los contenidos del documento. Para obtener demostraciones de cómo trabajar con los CustomXmlParts objetos y CustomXmlPart , vea el ejemplo de código Word-add-in-Work-with-custom-XML-parts .

Trabajar con todo el documento mediante el método getFileAsync

Se aplica a: complementos de panel de tareas para Word y PowerPoint

El método Document.getFileAsync y los miembros de los objetos File y Slice proporcionan funciones para obtener archivos de documentos completos de Word y PowerPoint en segmentos (fragmentos) de hasta 4 MB a la vez. Para más información, vea Procedimiento para obtener el documento completo de un complemento para PowerPoint o Word.

Objeto Mailbox

Se aplica a: complementos de Outlook

Los complementos de Outlook usan, principalmente, un subconjunto de la API que se expone a través del objeto Mailbox. Para tener acceso a los objetos y miembros específicamente para su uso en complementos de Outlook, como el objeto Item , use la propiedad mailbox del objeto Context para acceder al objeto Mailbox , como se muestra en la siguiente línea de código.

// Access the Item object.
const item = Office.context.mailbox.item;

Además, los complementos de Outlook pueden usar los siguientes objetos.

Objeto de Office: para inicialización.
Objeto Context: para obtener acceso al contenido y para mostrar las propiedades de idioma.
Objeto RoamingSettings: para guardar configuraciones personalizadas específicas del complemento de Outlook en el buzón del usuario donde está instalado el complemento.

Para obtener información sobre el uso de JavaScript en los complementos de Outlook, consulte Complementos de Office.

Compartir a través de