Adicionar propriedades aos valores de células básicas do Excel

Use propriedades em um valor básico de célula quando quiser que uma célula mantenha seu valor original stringdouble, ou Boolean e também exponha detalhes extras. Por exemplo, uma conta de restaurante pode permanecer 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 Visão geral dos tipos de dados nos complementos do Excel se você for novo nos tipos de dados do Excel.
• Examine o esquema JSON em Usar tipos de dados em Excel add-ins.
• Use Criar tipos de dados de entidade vinculada em suplementos do Excel quando seus dados vierem de uma fonte externa e devem ser atualizados de forma independente.

O exemplo a seguir mostra o número 14.67 com campos adicionados chamados Drinks, Food, Taxe Tip.

Quando os usuários abrirem o tipo de dados card, eles poderão ver os campos extras.

Valores básicos com propriedades também podem ser referenciados em fórmulas usando a notação de ponto.

Criar um valor de célula com propriedades

Use Range.valuesAsJson para criar um valor e definir suas propriedades em uma atribuição. O exemplo a seguir grava um número e adiciona detalhes da A1 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

Use esse padrão quando uma célula já contiver um valor básico e você quiser enriquecê-la sem alterar seu tipo subjacente. Primeiro, leia o valor usando valuesAsJson. Em seguida, verifique se o valor é um string, doubleou Boolean antes de adicionar propriedades.

O exemplo a seguir obtém o número em A1, preserva todas as 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();
    }
  });
}

Escolha um valor básico ou um valor de entidade

Adicionar propriedades a string, Boolean, e double tipos básicos é semelhante à adição de propriedades a valores de entidade, mas o comportamento é diferente em alguns aspectos importantes.

• Use um valor básico com propriedades quando as fórmulas devem continuar a tratar a célula como seu valor subjacente. Os tipos básicos não têm fallbacks de erro, portanto, os cálculos sempre podem continuar. Por exemplo, =SUM(A1:A3) ainda retorna 6 se A1 é um duplo com propriedades e A2 e A3 são números padrão.
• Quando um cálculo usa um valor básico, o resultado inclui apenas o valor subjacente. O resultado não mantém as propriedades de origem.
• Se você não especificar um ícone para um valor básico, a célula não mostrará nenhum ícone. Os valores de entidade mostram um ícone padrão quando nenhum ícone é especificado.

Valores de número formatados

Você pode aplicar formatação de número a valores de tipo CellValueType.double usando a numberFormat propriedade. O exemplo a seguir 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();
  });
}

Esse formato de número é o formato padrão para o valor. Se o usuário, ou outro código, aplicar um formato diferente à célula, esse formato substituirá o valor numberFormat.

Personalizar o layout do card

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

Para obter opções de layout e exemplos, consulte Usar cartões com tipos de dados de valor de célula.

Tipos de dados aninhados

Você pode aninhar outros tipos de dados dentro de um valor básico, incluindo valores de entidade e valores double, e adicionais stringBoolean e. O exemplo a seguir grava um valor de carga da bateria do computador em A1e, em seguida, adiciona uma entidade aninhada que descreve o computador e suas configuraçõ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 a seguir mostra o valor e o tipo de dados card para a entidade de laptop aninhada.

Compatibilidade

Em versões anteriores do Excel que não suportam o recurso de tipos de dados, os usuários veem um aviso de Tipo de Dados Indisponível . O valor ainda aparece na célula e continua funcionando com fórmulas e outros recursos do Excel. Se o valor for um número formatado, os cálculos usarão em basicValue vez do número formatado.

Em versões do Excel mais antigas que o Office 2016, o valor aparece na célula sem nenhum erro e é indistinguível de um valor básico.

Confira também

• Visão geral dos tipos de dados em suplementos do Excel
• Usar tipos de dados em suplementos do Excel
• Usar cartões com tipos de dados de valor de célula
• Criar tipos de dados de entidade vinculados em suplementos do Excel