Compartir a través de

Conceptos básicos de los tipos de datos de Excel

En este artículo se describe cómo usar la API de JavaScript de Excel para trabajar con tipos de datos. Presenta conceptos básicos que son fundamentales para el desarrollo de tipos de datos.

La propiedad valuesAsJson.

La valuesAsJson propiedad (o el singular valueAsJson para NamedItem) es integral para crear tipos de datos en Excel. Esta propiedad es una expansión de las propiedades values, como Range.values. Tanto las propiedades values como las valuesAsJson se usan para tener acceso al valor de una celda, pero la propiedad values solo devuelve uno de los cuatro tipos básicos: cadena, número, booleano o error (en forma de cadena). En cambio, valuesAsJson devuelve información expandida sobre los cuatro tipos básicos. Esta propiedad puede devolver tipos de datos como valores numéricos con formato, entidades e imágenes web.

Los siguientes objetos ofrecen la propiedad valuesAsJson.

Nota:

Algunos valores de celda cambian en función de la configuración regional del usuario. La propiedad valuesAsJsonLocal ofrece compatibilidad con la localización y está disponible en los mismos objetos que valuesAsJson.

Valores de celda

La propiedad valuesAsJson devuelve un alias de tipo CellValue, que es una unión de los siguientes tipos de datos.

El alias de tipo CellValue también devuelve el objeto CellValueExtraProperties que es una intersección con el resto de los tipos de *CellValue. No es un tipo de datos en sí mismo. Las propiedades del objeto CellValueExtraProperties se usan con todos los tipos de datos para especificar detalles relacionados con la sobrescritura de valores de celda.

Esquema JSON

Cada tipo de valor de celda devuelto por valuesAsJson usa un esquema de metadatos JSON diseñado para ese tipo. Además de las propiedades adicionales que son únicas para cada tipo de datos, todos estos esquemas de metadatos JSON tienen en común las propiedades type, basicType y basicValue.

type define el cellValueType de los datos. basicType siempre es de solo lectura y se usa como reserva cuando el tipo de datos no se admite o tiene un formato incorrecto. basicValue coincide con el valor que devolvería la propiedad values. basicValue se usa como reserva cuando los cálculos se topan con incompatibilidades, como una versión anterior de Excel que no admite la característica de tipos de datos. basicValue es de solo lectura para los ArrayCellValuetipos de datos , EntityCellValue, LinkedEntityCellValuey WebImageCellValue .

Además de los tres campos que comparten todos los tipos de datos, el esquema de metadatos JSON de cada *CellValue tiene propiedades disponibles según ese tipo. Por ejemplo, el tipo WebImageCellValue incluye las propiedades altText y attribution, mientras que el tipo EntityCellValue ofrece los campos properties y text.

En las secciones siguientes se muestran ejemplos de código JSON para el valor numérico con formato, el valor de entidad y los tipos de datos de imagen web.

Valores numéricos con formato

El objeto DoubleCellValue permite a los complementos de Excel definir una numberFormat propiedad para un valor. Una vez asignado, este formato de número recorre los cálculos con el valor y las funciones pueden devolverlo.

En el ejemplo de código JSON siguiente se muestra el esquema completo de un valor de número con formato. El myDate valor numérico con formato del ejemplo de código se muestra como 1/16/1990 en la interfaz de usuario de Excel. Si no se cumplen los requisitos mínimos de compatibilidad para la característica de tipos de datos, los cálculos usan el basicValue en lugar del número con formato.

// This is an example of the complete JSON of a formatted number value.
// In this case, the number is formatted as a date.
const myDate: Excel.DoubleCellValue = {
    type: Excel.CellValueType.double,
    basicValue: 32889.0,
    basicType: Excel.RangeValueType.double, // A read-only property. Used as a fallback in incompatible scenarios.
    numberFormat: "m/d/yyyy"
};

El formato de número se considera el formato predeterminado. Si el usuario u otro código aplica formato a una celda que contiene un número con formato, el formato aplicado invalida el formato del número.

Comience a experimentar con valores de número con formato abriendo Script Lab y desproteigiendo el fragmento de código Tipos de datos: números con formato en nuestra biblioteca de ejemplos.

Valores básicos de celda

Agregue propiedades a valores de celda básicos en Excel para asociar información adicional a los valores. De forma similar a los valores de entidad, puede agregar propiedades a los tipos básicos string, double y Boolean . Cada propiedad es un par clave-valor. En el ejemplo siguiente se muestra el número 104.67 (un doble) que representa una factura con campos agregados denominados Bebidas, Alimentos, Impuestos y Propina.

Captura de pantalla de los campos bebidas, alimentos, impuestos y propinas que se muestran para el valor de celda seleccionado.

Para obtener más información, vea Agregar propiedades a valores básicos de celda.

Valores de entidad

Un valor de entidad es un contenedor para tipos de datos, similar a un objeto en la programación orientada a objetos. Las entidades también admiten matrices como propiedades de un valor de entidad. El objeto EntityCellValue permite a los complementos definir propiedades como type, text, y properties. La propiedad properties permite al valor de la entidad definir y contener tipos de datos adicionales.

Las propiedades basicType y basicValue definen cómo leen los cálculos este tipo de datos de entidad si no se cumplen los requisitos mínimos de compatibilidad para usar tipos de datos. En ese escenario, este tipo de datos de entidad se muestra como un error #VALUE! en la interfaz de usuario de Excel.

En el ejemplo de código JSON siguiente se muestra el esquema completo de un valor de entidad que contiene texto, una imagen, una fecha y un valor de texto adicional.

// This is an example of the complete JSON for an entity value.
// The entity contains text and properties which contain an image, a date, and another text value.
const myEntity: Excel.EntityCellValue = {
    type: Excel.CellValueType.entity,
    text: "A llama",
    properties: {
        image: myImage,
        "start date": myDate,
        "quote": {
            type: Excel.CellValueType.string,
            basicValue: "I love llamas."
        }
    }, 
    basicType: Excel.RangeValueType.error, // A read-only property. Used as a fallback in incompatible scenarios.
    basicValue: "#VALUE!" // A read-only property. Used as a fallback in incompatible scenarios.
};

Para explorar los tipos de datos de entidad, empiece por ir a Script Lab en Excel y abrir tipos de datos: Crear tarjetas de entidad a partir de datos en un fragmento de código de tabla en nuestra biblioteca de ejemplos. Los fragmentos de código Tipos de datos: Valores de entidad con referencias y Tipos de datos: propiedades de atribución de valores de entidad ofrecen una visión más detallada de las características de la entidad.

Valores de celda de entidad vinculada

Los valores de celda de entidad vinculada, o objetos LinkedEntityCellValue , son tipos de datos integrados de orígenes de datos externos y pueden mostrar los datos como una tarjeta de entidad. Permiten escalar los tipos de datos para representar grandes conjuntos de datos sin descargar todos los datos en el libro. Los dominios de datos Stocks y Geography disponibles a través de la interfaz de usuario de Excel proporcionan valores de celda de entidad vinculada.

Los valores de celda de entidad vinculada están vinculados a un origen de datos externo. Proporcionan las siguientes ventajas sobre los valores de entidad normales:

  • Los valores de celda de entidad vinculada pueden anidar y los valores de celda de entidad vinculada anidada no se recuperan hasta que el usuario o la hoja de cálculo hacen referencia a ellos. Esto ayuda a reducir el tamaño del archivo y mejorar el rendimiento del libro.
  • Excel usa una memoria caché para permitir que distintas celdas hagan referencia al mismo valor de celda de entidad vinculada sin problemas. Esto también mejora el rendimiento del libro.

Para obtener más información, consulte Creación de valores de celda de entidad vinculada.

Valores de imagen web

El objetoWebImageCellValuecrea la capacidad de almacenar una imagen como partede una entidad o como un valor independiente en un intervalo. Este objeto ofrece muchas propiedades, incluidas address, altText, y relatedImagesAddress.

Las propiedades basicType y basicValue definen cómo leen los cálculos el tipo de datos de imagen web si no se cumplen los requisitos mínimos de compatibilidad para usar la característica de tipos de datos. En ese escenario, este tipo de datos de imagen web se muestra como un error #VALUE! en la interfaz de usuario de Excel.

En el ejemplo de código JSON siguiente se muestra el esquema completo de una imagen web.

// This is an example of the complete JSON for a web image.
const myImage: Excel.WebImageCellValue = {
    type: Excel.CellValueType.webImage,
    address: "https://bit.ly/2YGOwtw", 
    basicType: Excel.RangeValueType.error, // A read-only property. Used as a fallback in incompatible scenarios.
    basicValue: "#VALUE!" // A read-only property. Used as a fallback in incompatible scenarios.
};

Pruebe los tipos de datos de imágenes web abriendo Script Lab y seleccionando el fragmento de código Tipos de datos: imágenes web en nuestra biblioteca de ejemplos.

Compatibilidad con errores mejorada

Las API de tipos de datos exponen errores existentes de la interfaz de usuario de Excel como objetos. Ahora que estos errores son accesibles como objetos, los complementos pueden definir o recuperar propiedades como type, errorType, y errorSubType.

A continuación se muestra una lista de todos los objetos de error con compatibilidad expandida a través de tipos de datos.

Cada uno de los objetos de error puede tener acceso a una enumeración a través de la propiedad errorSubType, y esta enumeración contiene datos adicionales sobre el error. Por ejemplo, el objeto de error BlockedErrorCellValue puede tener acceso a la enumeración BlockedErrorCellValueSubType. La enumeración BlockedErrorCellValueSubType ofrece datos adicionales sobre lo que causó el error.

Para más información sobre los objetos de error de tipos de datos, consulte el fragmento Tipos de datos: Establecer valores de error en nuestra biblioteca Script LabSamples.

Pasos siguientes

Obtenga información sobre cómo los tipos de datos de entidad amplían el potencial de los complementos de Excel más allá de una cuadrícula 2 dimensiones con el artículo Uso de tarjetas con tipos de datos de valor de entidad .

Use el ejemplo Crear y explorar tipos de datos en Excel en nuestro repositorio OfficeDev/Office-Add-in-samples para experimentar más profundamente con los tipos de datos mediante la creación y la transferencia local de un complemento que crea y edita tipos de datos en un libro.

Vea también

  • Last updated on