Adición de propiedades a 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 14.67 (un doble) que representa una factura con campos agregados denominados Bebidas, Alimentos, Impuestos y Propina.

Si el usuario decide mostrar la tarjeta de tipo de datos, verá los valores de los campos.

Las propiedades de valor de celda también se pueden usar en fórmulas.

Creación de un valor de celda con propiedades

Para crear un valor de celda y agregarle propiedades, use Range.valuesAsJson para asignar propiedades. En el ejemplo de código siguiente se muestra cómo crear un nuevo número en la celda A1. Agrega la comida, bebidas y propiedades adicionales que describen una factura en un restaurante. Asigna una descripción JSON de las propiedades a valuesAsJson.

async function createNumberProperties() {
  await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const range = sheet.getRange("A1");
    range.valuesAsJson = [
      [
        {
          type: Excel.CellValueType.double,
          basicType: Excel.RangeValueType.double,
          basicValue: 14.67,
          properties: {
            Food: {
              type: Excel.CellValueType.string,
              basicType: Excel.RangeValueType.string,
              basicValue: "Sandwich and fries"
            },
            Drinks: {
              type: Excel.CellValueType.string,
              basicType: Excel.RangeValueType.string,
              basicValue: "Soda"
            },
            Tax: {
              type: Excel.CellValueType.double,
              basicType: Excel.RangeValueType.double,
              basicValue: 5.5
            },
            Tip: {
              type: Excel.CellValueType.double,
              basicType: Excel.RangeValueType.double,
              basicValue: 21
            }
          }
        }
      ]
    ];
    await context.sync();
  });
}

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.

Adición de propiedades a un valor existente

Para agregar propiedades a un valor existente, primero obtenga el valor de la celda mediante valuesAsJsony, a continuación, agréguele un objeto JSON de propiedades. En el ejemplo siguiente se muestra cómo obtener el valor numérico de la celda A1 y asignarle una propiedad denominada Precision . Tenga en cuenta que debe comprobar el tipo del valor para asegurarse de que es un tipo básico de cadena, doble o booleano .

async function addPropertyToNumber() {
    await Excel.run(async (context) => {
        let sheet = context.workbook.worksheets.getActiveWorksheet();
        let range = sheet.getRange("A1");
        range.load("valuesAsJson");
        await context.sync();
        let cellValue = range.valuesAsJson[0][0] as any;

        // Only apply this property to a double.
        if (cellValue.basicType === "Double") {
            cellValue.properties = {
                Precision: {
                    type: Excel.CellValueType.double,
                    basicValue: 4
                }
            };
            range.valuesAsJson = [[cellValue]];
            await context.sync();
        }
    });
}

Diferencias con respecto a los valores de entidad

Agregar propiedades a tipos básicos de cadena, booleano y doble es similar a agregar propiedades a valores de entidad. Sin embargo, hay diferencias.

• Los tipos básicos tienen una reserva que no es de error para que los cálculos puedan funcionar en ellos. Por ejemplo, considere la fórmula =SUM(A1:A3) donde A1 es 1, A2 es 2 y A3 es 3. A1 es un valor doble con propiedades, mientras que A2 y A3 no tienen propiedades. La suma devuelve el resultado correcto de 6. La fórmula no funcionaría si A1 fuera un valor de entidad.
• Cuando se usa el valor de un tipo básico en un cálculo, las propiedades se excluyen en el resultado. En el ejemplo anterior de =SUM(A1:A3) donde A1 es un valor doble con propiedades, el resultado de 6 no tiene ninguna propiedad.
• Si no se especifica ningún icono para un tipo básico, la celda no muestra ningún icono. Pero si un valor de entidad no especifica un icono, muestra un icono predeterminado en el valor de celda.

Valores numéricos con formato

Puede aplicar formato de número a valores de tipo CellValueType.double. Use la numberFormat propiedad en el esquema JSON para especificar un formato numérico. En el ejemplo de código siguiente se muestra el esquema completo de un valor numérico con formato de moneda. El valor de número con formato del ejemplo de código se muestra como $24,00 en la interfaz de usuario de Excel.

// This is an example of the complete JSON of a formatted number value with a property.
// In this case, the number is formatted as currency.
async function createCurrencyValue() {
    await Excel.run(async (context) => {
        const sheet = context.workbook.worksheets.getActiveWorksheet();
        const range = sheet.getRange("A1");
        range.valuesAsJson = [
            [
                {
                    type: Excel.CellValueType.double,
                    basicType: Excel.RangeValueType.double,
                    basicValue: 24,
                    numberFormat: "$0.00",
                    properties: {
                        Name: {
                            type: Excel.CellValueType.string,
                            basicValue: "dollar"
                        }
                    }
                }
            ]
        ];
        await context.sync();
    });
}

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.

Diseño de tarjeta

Los valores de celda con propiedades tienen una tarjeta de tipo de datos predeterminada que el usuario puede ver. Puede proporcionar un diseño de tarjeta personalizado que se usará en lugar del diseño de tarjeta predeterminado para mejorar la experiencia del usuario al ver las propiedades. Para ello, agregue la propiedad layouts a la descripción json.

Para obtener más información, vea Usar tarjetas con tipos de datos de valor de celda.

Tipos de datos anidados

Puede anidar tipos de datos en un valor de celda, como valores de entidad adicionales, así como cadenas, valores dobles y booleanos. En el ejemplo de código siguiente se muestra cómo crear un valor de celda que representa el estado de carga en una batería del equipo. Contiene un valor de entidad anidada que describe las propiedades del equipo para el consumo de energía y el estado de carga. El valor de la entidad de equipo también contiene un valor de cadena anidada que describe el plan de energía del equipo.

async function createNumberWithNestedEntity() {
    await Excel.run(async (context) => {
        const sheet = context.workbook.worksheets.getActiveWorksheet();
        const range = sheet.getRange("A1");
        range.valuesAsJson = [
            [
                {
                    type: Excel.CellValueType.double,
                    basicType: Excel.RangeValueType.double,
                    layouts: {
                        compact: {
                            icon: "Battery10"
                        }
                    },
                    basicValue: 0.7,
                    numberFormat: "00%",
                    properties: {
                        Computer: {
                            type: Excel.CellValueType.entity,
                            text: "Laptop",
                            properties: {
                                "Power Consumption": {
                                    type: Excel.CellValueType.double,
                                    basicType: Excel.RangeValueType.double,
                                    basicValue: 0.25,
                                    numberFormat: "00%",
                                    layouts: {
                                        compact: {
                                            icon: "Power"
                                        }
                                    },
                                    properties: {
                                        plan: {
                                            type: Excel.CellValueType.string,
                                            basicType: Excel.RangeValueType.string,
                                            basicValue: "Balanced"
                                        }
                                    }
                                },
                                Charging: {
                                    type: Excel.CellValueType.boolean,
                                    basicType: Excel.RangeValueType.boolean,
                                    basicValue: true
                                }
                            }
                        }
                    }
                }
            ]
        ];
        await context.sync();
    });
}

En la imagen siguiente se muestra el valor numérico y la tarjeta de tipo de datos de la entidad de portátil anidada.

Compatibilidad

En versiones anteriores de Excel que no admiten la característica de tipos de datos, los usuarios ven una advertencia de Tipo de datos no disponible. El valor todavía se muestra en la celda y las funciones según lo esperado con fórmulas y otras características de Excel. Si el valor es un número con formato, los cálculos usan en basicValue lugar del número con formato.

En las versiones de Excel anteriores a Office 2016, el valor se muestra en la celda sin ningún error y no se puede diferenciar de un valor básico.

Vea también

• Conceptos básicos de los tipos de datos de la API de JavaScript de Excel