Adicionar propriedades a valores básicos de células

Adicione propriedades a valores básicos de células no Excel para associar informações adicionais aos valores. Semelhante aos valores de entidade, pode adicionar propriedades aos tipos básicos de cadeia, duplo e booleano . Cada propriedade é um par chave/valor. O exemplo seguinte mostra o número 14,67 (um duplo) que representa uma fatura com campos adicionados denominados Bebidas, Alimentação, Impostos e Sugestão.

Se o utilizador optar por mostrar o tipo de dados card, verá os valores dos campos.

As propriedades do valor da célula também podem ser utilizadas em fórmulas.

Criar um valor de célula com propriedades

Para criar um valor de célula e adicionar propriedades ao mesmo, utilize Range.valuesAsJson para atribuir propriedades. O seguinte exemplo de código mostra como criar um novo número na célula A1. Adiciona a Comida, Bebidas e propriedades adicionais descrevendo uma conta em um restaurante. Atribui uma descrição JSON das propriedades 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();
  });
}

Observação

Alguns valores de célula mudam com base na localidade de um usuário. A propriedade valuesAsJsonLocal oferece suporte à localização e está disponível em todos os mesmos objetos que valuesAsJson.

Adicionar propriedades a um valor existente

Para adicionar propriedades a um valor existente, primeiro obtenha o valor da célula com valuesAsJsone, em seguida, adicione um objeto JSON de propriedades ao mesmo. O exemplo seguinte mostra como obter o valor de número da célula A1 e atribuir-lhe uma propriedade com o nome Precisão . Tenha em atenção que deve marcar o tipo do valor para garantir que é um tipo básico de cadeia, duplo ou 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();
        }
    });
}

Diferenças dos valores de entidade

Adicionar propriedades a tipos básicos de cadeia, Booleano e duplo é semelhante a adicionar propriedades a valores de entidade. No entanto, existem diferenças.

• Os tipos básicos têm uma contingência sem erros para que os cálculos possam operar nos mesmos. Por exemplo, considere a fórmula =SOMA(A1:A3) em queA1 é 1, A2 é 2 e A3 é 3. A1 é um duplo com propriedades, enquanto A2 e A3 não têm propriedades. A soma devolve o resultado correto de 6. A fórmula não funcionaria se A1 fosse um valor de entidade.
• Quando o valor de um tipo básico é utilizado num cálculo, as propriedades são excluídas no resultado. No exemplo anterior de =SOMA(A1:A3) em que A1 é um duplo com propriedades, o resultado de 6 não tem quaisquer propriedades.
• Se não for especificado nenhum ícone para um tipo básico, a célula não mostrará nenhum ícone. No entanto, se um valor de entidade não especificar um ícone, mostra um ícone predefinido no valor da célula.

Valores de número formatados

Pode aplicar formatação de números a valores do tipo CellValueType.double. Utilize a numberFormat propriedade no esquema JSON para especificar um formato de número. O seguinte exemplo de código mostra o esquema completo de um valor numérico formatado como moeda. O valor de número formatado no exemplo de código é apresentado como $24,00 na IU do 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();
    });
}

A formatação de números é considerada o formato predefinido. Se o utilizador, ou outro código, aplicar formatação a uma célula que contenha um número formatado, o formato aplicado substitui o formato do número.

Esquema de cartão

Os valores das células com propriedades têm um tipo de dados predefinido card que o utilizador pode ver. Pode fornecer um esquema de card personalizado para utilizar em vez do esquema de card predefinido para melhorar a experiência do utilizador ao visualizar as propriedades. Para tal, adicione a propriedade layouts à descrição JSON.

Para obter mais informações, veja Utilizar cartões com tipos de dados de valor de célula.

Tipos de dados aninhados

Pode aninhar tipos de dados num valor de célula, como valores de entidade adicionais, bem como cadeias, duplos e Booleanos. O seguinte exemplo de código mostra como criar um valor de célula que representa a carga status numa bateria de computador. Contém um valor de entidade aninhado que descreve as propriedades do computador para consumo de energia e carregamento status. O valor da entidade do computador também contém um valor de cadeia aninhado que descreve o esquema de energia do computador.

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 de número e o tipo de dados card para a entidade de portátil aninhado.

Compatibilidade

Em versões anteriores do Excel que não suportam a funcionalidade de tipos de dados, os utilizadores veem um aviso de Tipo de Dados Indisponível. O valor continua a ser apresentado na célula e funciona conforme esperado 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.

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

Confira também

• Conceitos básicos dos tipos de dados da API JavaScript do Excel