Uso de tipos de datos en complementos de Excel

Cuando el complemento necesite más que cadenas, números y booleanos, use tipos de datos de Excel. Los tipos de datos permiten devolver valores mejorados, como fechas con formato, tarjetas de entidad, registros vinculados e imágenes web, a la vez que se admiten los cálculos de la hoja de cálculo.

En este artículo se explica la valuesAsJson API que alimenta los tipos de datos y muestra cuándo usar los tipos de valor de celda principales. Para obtener información general sobre una característica, vea Información general sobre los tipos de datos en complementos de Excel.

Para probar estos conceptos de inmediato, abra Script Lab en Excel y examine los ejemplos de tipos de datos en la biblioteca de ejemplos.

La propiedad valuesAsJson.

La valuesAsJson propiedad es la API principal para leer y escribir tipos de datos de Excel. La propiedad singular valueAsJson de NamedItem tiene el mismo propósito para un único elemento con nombre.

valuesAsJson se expande en propiedades como Range.values. La values propiedad solo devuelve uno de los cuatro tipos de valor de celda básicos: cadena, número, booleano o error. Por el contrario, valuesAsJson devuelve una estructura JSON expandida para esos tipos básicos y para los tipos de datos, como números con formato, entidades e imágenes web.

Los objetos siguientes exponen valuesAsJson.

Nota:

Algunos valores de celda cambian en función de la configuración regional del usuario. Use valuesAsJsonLocal cuando necesite valores localizados. Está disponible en los mismos objetos valuesAsJsonque .

Valores de celda

valuesAsJson devuelve el alias de tipo CellValue . CellValue es una unión de varios tipos de valor de celda.

Los tipos que usan la mayoría de los complementos son:

La unión completa CellValue incluye los siguientes tipos.

CellValue es una intersección con CellValueExtraProperties. CellValueExtraProperties no es un tipo de datos por sí mismo. Agrega propiedades que le ayudan a controlar cómo se sobrescriben los valores de celda.

Esquema JSON

Cada valor que valuesAsJson devuelve usa un esquema de metadatos JSON diseñado para ese tipo de valor de celda. Aunque cada tipo tiene sus propias propiedades, todos los esquemas comparten type, basicTypey basicValue.

type define CellValueType. basicType es de solo lectura y proporciona el tipo de reserva cuando el tipo de datos no se admite o tiene un formato incorrecto. basicValue coincide con el valor devuelto por la values propiedad y actúa como reserva cuando los cálculos encuentran escenarios incompatibles, como una versión anterior de Excel que no admite tipos de datos. basicValue es de solo lectura para ArrayCellValue, EntityCellValue, LinkedEntityCellValuey WebImageCellValue.

Más allá de esos campos compartidos, cada *CellValue tipo tiene su propio esquema. Por ejemplo, WebImageCellValue incluye altText y attribution, mientras que EntityCellValue incluye properties y text.

En las secciones siguientes se muestran patrones comunes para números con formato, valores básicos con propiedades adicionales, valores de entidad, entidades vinculadas, imágenes web y errores mejorados.

Valores numéricos con formato

Use DoubleCellValue cuando el valor numérico subyacente sea importante, pero también quiere que Excel mantenga un formato de presentación específico con ese valor. Un escenario común es devolver un valor de fecha serie y mostrarlo como una fecha en la hoja de cálculo.

En el ejemplo siguiente se muestra el esquema JSON completo para un número con formato. En este ejemplo, myDate se muestra como 1/16/1990 en la interfaz de usuario de Excel. Si no se cumplen los requisitos mínimos de compatibilidad para los tipos de datos, los cálculos usan basicValue.

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 de es DoubleCellValue el formato predeterminado. Si un usuario u otra parte del complemento aplica formato a la celda más adelante, ese formato aplicado invalida el formato del valor.

Para experimentar con valores de número con formato, abra Script Lab y ejecute el ejemplo Tipos de datos: números con formato.

Valores básicos de celda

Puede agregar propiedades a valores básicos de Excel para asociar información adicional con ellos. Este patrón funciona con los tipos básicos de cadena, doble y booleano . Úselo cuando desee que un valor de celda simple lleve campos relacionados sin convertir el valor en una entidad completa.

Por ejemplo, un total de factura puede incluir campos relacionados como 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 ver el tutorial completo, vea Agregar propiedades a los valores básicos de celda de Excel.

Valores de entidad

EntityCellValue puede almacenar texto, tipos de datos anidados y matrices, y Excel puede mostrar esos datos en una tarjeta de entidad.

En el ejemplo siguiente se muestra el esquema JSON completo para un valor de entidad que representa una factura. La entidad incluye texto para mostrar más propiedades para una imagen, una fecha de vencimiento y un valor de estado.

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

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

Importante

Un valor de entidad puede definir una referencedValues matriz que almacena valores de celda adicionales. El índice hace referencia a estos valores desde dentro de propertiesla entidad .

  • La referencedValues matriz solo se admite en la entidad de nivel raíz de un árbol de valores de celda.
  • Las entidades anidadas, que son entidades que se usan como valores de propiedad dentro de otra entidad, no deben definir su propia referencedValues.
  • Si una entidad anidada incluye una referencedValues matriz, la API de Excel de JavaScript produce un GeneralException error en el código de complemento o script, o Bien Excel muestra un error #VALUE! cuando una función personalizada genera el valor.

Para hacer referencia a valores de una entidad anidada, use índices ReferenceCellValue que apunten a la matriz de la referencedValues entidad raíz.

Para explorar los tipos de datos de entidad, abra Script Lab y ejecute Tipos de datos: Crear tarjetas de entidad a partir de datos de una tabla. Para obtener ejemplos más profundos, vea Tipos de datos: valores de entidad con referencias y Tipos de datos: propiedades de atribución de valores de entidad.

Valores de celda de entidad vinculada

LinkedEntityCellValue representa una entidad conectada a un origen de datos externo. Use entidades vinculadas cuando necesite tarjetas para conjuntos de datos grandes o actualizados con frecuencia y no quiera cargar todos los detalles en el libro a la vez.

Los dominios de datos Stocks y Geography disponibles en la interfaz de usuario de Excel son ejemplos de valores de celda de entidad vinculada.

Los valores de celda de entidad vinculada ofrecen las siguientes ventajas sobre los valores de entidad normales.

  • Los valores de celda de entidad vinculada pueden anidar y Excel no recupera entidades vinculadas anidadas hasta que el usuario o la hoja de cálculo hacen referencia a ellas. Este comportamiento ayuda a reducir el tamaño de los archivos y a mejorar el rendimiento del libro.
  • Excel usa una memoria caché para que distintas celdas puedan hacer referencia al mismo valor de celda de entidad vinculada. Esto también ayuda al rendimiento del libro.

Para obtener más información sobre la implementación, consulte Creación de tipos de datos de entidad vinculada en complementos de Excel.

Valores de imagen web

Use WebImageCellValue cuando el complemento necesite almacenar una imagen en un intervalo o como parte de un valor de entidad. Este tipo incluye propiedades como address, altTexty relatedImagesAddress.

Las basicType propiedades y basicValue definen cómo los cálculos leen una imagen web cuando no se cumplen los requisitos mínimos de compatibilidad para los tipos de datos. En ese caso, la imagen web se muestra como un error #VALUE! en la interfaz de usuario de Excel.

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

const myImage: Excel.WebImageCellValue = {
    type: Excel.CellValueType.webImage,
    address: "https://bit.ly/2YGOwtw",
    basicType: Excel.RangeValueType.error,
    basicValue: "#VALUE!"
};

Para probar los tipos de datos de imágenes web, abra Script Lab y ejecute Tipos de datos: imágenes web.

Compatibilidad con errores mejorada

Las API de tipos de datos exponen los errores existentes de la interfaz de usuario de Excel como objetos. Este enfoque permite que el complemento defina o recupere propiedades como type, errorTypey errorSubType.

Los siguientes objetos de error han ampliado la compatibilidad a través de tipos de datos.

Cada objeto de error puede tener acceso a una enumeración a través de errorSubType. Esa enumeración proporciona más detalles sobre el error específico. Por ejemplo, BlockedErrorCellValueSubType proporciona información adicional sobre por qué se produjo.BlockedErrorCellValue

Para obtener más información, abra Script Lab y ejecute Tipos de datos: Establecer valores de error.

Pasos siguientes

Vea también

  • Last updated on