Conceptos básicos de los tipos de datos de Excel

  • Artículo

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 FormattedNumberCellValue permite a los complementos de Excel definir numberFormat una 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.FormattedNumberCellValue = {
    type: Excel.CellValueType.formattedNumber,
    basicValue: 32889.0,
    basicType: Excel.RangeValueType.double, // A read-only property. Used as a fallback in incompatible scenarios.
    numberFormat: "m/d/yyyy"
};

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 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.
};

Los valores de entidad también ofrecen una propiedad layouts que crea una tarjeta para la entidad. La tarjeta se muestra como una ventana modal en la interfaz de usuario de Excel y puede mostrar información adicional contenida en el valor de entidad, más allá de lo que está visible en la celda. Para obtener más información, consulte Usar tarjetas con tipos de datos de valor de entidad.

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.

Entidades vinculadas

Los valores de entidad vinculados u objetos LinkedEntityCellValue son un tipo de valor de entidad. Estos objetos integran los datos proporcionados por un servicio externo y pueden mostrar estos datos como una tarjeta de entidad, al igual que los valores de entidad normales. Los tipos de datos de Cotizaciones e Información geográfica disponibles a través de la interfaz de usuario de Excel son valores de entidad vinculados.

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