Adicionar propriedades a valores básicos de células do Excel

Utilize propriedades num valor de célula básico quando quiser que uma célula mantenha o respetivo valor original string, doubleou Boolean e também exponha detalhes adicionais. Por exemplo, uma fatura de restaurante pode manter um número para cálculos, ao mesmo tempo que mostra Food, Drinks, Taxe Tip no tipo de dados card e em fórmulas.

Este artigo mostra como criar um valor básico com propriedades, atualizar um valor existente, formatar valores numéricos e adicionar tipos de dados aninhados.

• Comece com a Descrição geral dos tipos de dados nos suplementos do Excel se não estiver familiarizado com os tipos de dados do Excel.
• Reveja o esquema JSON em Utilizar tipos de dados em suplementos do Excel.
• Utilize Criar tipos de dados de entidades ligadas em suplementos do Excel quando os seus dados provêm de uma origem externa e devem ser atualizados de forma independente.

O exemplo seguinte mostra o número 14.67 com campos adicionados denominados Drinks, Food, Taxe Tip.

Quando os utilizadores abrem o tipo de dados card, podem ver os campos adicionais.

Os valores básicos com propriedades também podem ser referenciados em fórmulas através da notação de pontos.

Criar um valor de célula com propriedades

Utilize Range.valuesAsJson para criar um valor e definir as respetivas propriedades numa atribuição. O exemplo seguinte escreve um número A1 e adiciona os detalhes da fatura como propriedades.

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

Adicionar propriedades a um valor existente

Utilize este padrão quando uma célula já tiver um valor básico e quiser melhorá-la sem alterar o tipo subjacente. Primeiro, leia o valor com valuesAsJson. Em seguida, verifique se o valor é um string, doubleou Boolean antes de adicionar propriedades.

O exemplo seguinte obtém o número em A1, preserva quaisquer propriedades existentes e adiciona uma Precision propriedade.

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

Escolher um valor básico ou um valor de entidade

Adicionar propriedades a string, Booleane double tipos básicos é semelhante a adicionar propriedades a valores de entidade, mas o comportamento é diferente de algumas formas importantes.

• Utilize um valor básico com propriedades quando as fórmulas devem continuar a tratar a célula como o valor subjacente. Os tipos básicos não têm contingências de erros, pelo que os cálculos podem sempre prosseguir. Por exemplo, =SUM(A1:A3) continua a devolver 6 se A1 for um valor duplo com propriedades e A2 e A3 forem números padrão.
• Quando um cálculo utiliza um valor básico, o resultado inclui apenas o valor subjacente. O resultado não mantém as propriedades de origem.
• Se não especificar um ícone para um valor básico, a célula não mostra nenhum ícone. Os valores de entidade mostram um ícone predefinido quando não é especificado nenhum ícone.

Valores de número formatados

Pode aplicar formatação de números a valores do tipo CellValueType.double através da numberFormat propriedade . O exemplo seguinte cria um valor de moeda e adiciona uma propriedade descritiva.

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 é o formato predefinido do valor. Se o utilizador, ou outro código, aplicar um formato diferente à célula, esse formato substitui o valor de numberFormat.

Personalizar o esquema de card

Os valores básicos com propriedades utilizam um tipo de dados predefinido card. Para mostrar as propriedades de uma forma mais útil, adicione a layouts propriedade à descrição JSON e defina um esquema de card personalizado.

Para obter opções de esquema e exemplos, veja Utilizar cartões com tipos de dados de valor de célula.

Tipos de dados aninhados

Pode aninhar outros tipos de dados dentro de um valor básico, incluindo valores de entidade e valores adicionais string, doublee Boolean . O exemplo seguinte escreve um valor de carga da bateria do computador em A1e, em seguida, adiciona uma entidade aninhada que descreve o computador e as respetivas definições de energia.

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

A imagem seguinte mostra o valor e o tipo de dados card para a entidade de portátil aninhada.

Compatibilidade

Em versões anteriores do Excel que não suportam a funcionalidade de tipos de dados, os utilizadores veem um aviso Tipo de Dados Indisponível . O valor continua a aparecer na célula e continua a funcionar com fórmulas e outras funcionalidades do Excel. Se o valor for um número formatado, os cálculos utilizam o basicValue em vez do número formatado.

Em versões do Excel anteriores ao Office 2016, o valor aparece na célula sem erros e é indistinguível de um valor básico.

Confira também

• Visão geral dos tipos de dados em suplementos do Excel
• Utilizar tipos de dados em suplementos do Excel
• Utilizar cartões com tipos de dados de valor de célula
• Criar tipos de dados de entidades ligadas em suplementos do Excel