Agregar propiedades a valores de celda básicos de Excel

Use propiedades en un valor de celda básico cuando desee que una celda conserve su valor original string, doubleo Boolean y también exponga detalles adicionales. Por ejemplo, una factura de restaurante puede permanecer un número para los cálculos, mientras que también muestra Food, Drinks, Taxy Tip en la tarjeta de tipo de datos y en fórmulas.

En este artículo se muestra cómo crear un valor básico con propiedades, actualizar un valor existente, dar formato a los valores numéricos y agregar tipos de datos anidados.

• Comience con Información general de los tipos de datos en complementos de Excel si no está familiarizado con los tipos de datos de Excel.
• Revise el esquema JSON en Usar tipos de datos en complementos de Excel.
• Use Crear tipos de datos de entidad vinculada en complementos de Excel cuando los datos proceden de un origen externo y deben actualizarse de forma independiente.

En el ejemplo siguiente se muestra el número 14.67 con campos agregados denominados Drinks, Food, Taxy Tip.

Cuando los usuarios abren la tarjeta de tipo de datos, pueden ver los campos adicionales.

También se puede hacer referencia a los valores básicos con propiedades en fórmulas mediante la notación de puntos.

Creación de un valor de celda con propiedades

Use Range.valuesAsJson para crear un valor y definir sus propiedades en una asignación. En el ejemplo siguiente se escribe un número en A1 y se agregan detalles de factura como propiedades.

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();
  });
}

Adición de propiedades a un valor existente

Use este patrón cuando una celda ya contenga un valor básico y quiera enriquecerlo sin cambiar su tipo subyacente. En primer lugar, lea el valor mediante valuesAsJson. A continuación, compruebe que el valor es , stringdoubleo Boolean antes de agregar propiedades.

En el ejemplo siguiente se obtiene el número de A1, se conserva cualquier propiedad existente y se agrega una Precision propiedad .

async function addPropertyToNumber() {
  await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const range = sheet.getRange("A1");

    range.load("valuesAsJson");
    await context.sync();

    const cellValue = range.valuesAsJson[0][0] as any;

    // Only apply this property to a double.
    if (cellValue.basicType === Excel.RangeValueType.double) {
      cellValue.properties = {
        ...(cellValue.properties ?? {}),
        Precision: {
          type: Excel.CellValueType.double,
          basicValue: 4
        }
      };

      range.valuesAsJson = [[cellValue]];
      await context.sync();
    }
  });
}

Elegir un valor básico o un valor de entidad

Agregar propiedades a string, Booleany double tipos básicos es similar a agregar propiedades a valores de entidad, pero el comportamiento es diferente de varias maneras importantes.

• Use un valor básico con propiedades cuando las fórmulas deben seguir tratando la celda como su valor subyacente. Los tipos básicos no tienen reservaciones de error, por lo que los cálculos siempre pueden continuar. Por ejemplo, =SUM(A1:A3) sigue devuelve 6 si A1 es un valor doble con propiedades y A2 son A3 números estándar.
• Cuando un cálculo usa un valor básico, el resultado incluye solo el valor subyacente. El resultado no conserva las propiedades de origen.
• Si no especifica un icono para un valor básico, la celda no muestra ningún icono. Los valores de entidad muestran un icono predeterminado cuando no se especifica ningún icono.

Valores numéricos con formato

Puede aplicar formato de número a valores de tipo CellValueType.double mediante la numberFormat propiedad . En el ejemplo siguiente se crea un valor de moneda y se agrega una propiedad descriptiva.

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: "Price"
            }
          }
        }
      ]
    ];

    await context.sync();
  });
}

Este formato de número es el formato predeterminado para el valor. Si el usuario u otro código aplica un formato diferente a la celda, ese formato invalida el valor de numberFormat.

Personalización del diseño de la tarjeta

Los valores básicos con propiedades usan una tarjeta de tipo de datos predeterminada. Para mostrar las propiedades de una manera más útil, agregue la layouts propiedad a la descripción JSON y defina un diseño de tarjeta personalizado.

Para ver opciones de diseño y ejemplos, consulte Uso de tarjetas con tipos de datos de valor de celda.

Tipos de datos anidados

Puede anidar otros tipos de datos dentro de un valor básico, incluidos los valores de entidad y valores adicionales string, doubley Boolean . En el ejemplo siguiente se escribe un valor de carga de batería del equipo en y, a A1continuación, se agrega una entidad anidada que describe el equipo y su configuración de energía.

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 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 Tipo de datos no disponible . El valor sigue apareciendo en la celda y sigue funcionando 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 aparece en la celda sin ningún error y es indistinguible de un valor básico.

Vea también

• Información general sobre los tipos de datos en complementos de Excel
• Uso de tipos de datos en complementos de Excel
• Uso de tarjetas con tipos de datos de valor de celda
• Creación de tipos de datos de entidad vinculada en complementos de Excel