Добавление свойств к базовым значениям ячейки

Добавьте свойства к базовым значениям ячеек в Excel, чтобы связать дополнительные сведения со значениями. Как и значения сущностей, можно добавлять свойства к базовым типам string, double и boolean . Каждое свойство является парой "ключ-значение". В следующем примере показано число 14,67 (двойник), представляющее счет с добавленными полями с именами "Напитки", "Еда", "Налог" и "Чаевые".

Если пользователь решит отобразить тип данных карта, он увидит значения для полей.

Свойства значения ячейки также можно использовать в формулах.

Создание значения ячейки со свойствами

Чтобы создать значение ячейки и добавить к нему свойства, используйте Range.valuesAsJson для назначения свойств. В следующем примере кода показано, как создать новое число в ячейке A1. Он добавляет продукты питания, напитки и дополнительные свойства, описывающие счет в ресторане. Он назначает описание свойств valuesAsJsonв формате JSON .

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

Примечание.

Некоторые значения ячеек изменяются в зависимости от языкового стандарта пользователя. Свойство valuesAsJsonLocal предлагает поддержку локализации и доступно для всех тех же объектов, что и valuesAsJson.

Добавление свойств к существующему значению

Чтобы добавить свойства к существующему значению, сначала получите значение из ячейки с помощью valuesAsJson, а затем добавьте в него объект JSON свойств. В следующем примере показано, как получить числовое значение из ячейки A1 и присвоить ей свойство с именем Precision . Обратите внимание, что следует проверка тип значения, чтобы он был строковым, двойным или логическим базовым типом.

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

Отличия от значений сущностей

Добавление свойств к строкам, логическим и двойным базовым типам аналогично добавлению свойств к значениям сущностей. Однако существуют различия.

• Базовые типы имеют резервный вариант без ошибок, чтобы вычисления могли работать с ними. Например, рассмотрим формулу =СУММ(A1:A3), где A1 — 1, A2 — 2, А3 — 3. A1 — это двойник со свойствами, а У A2 и A3 нет свойств. Сумма возвращает правильный результат 6. Формула не будет работать, если A1 является значением сущности.
• Если в вычислении используется значение базового типа, свойства исключаются в результате. В предыдущем примере =SUM(A1:A3), где A1 — это двойник со свойствами, результат 6 не имеет никаких свойств.
• Если для базового типа не указан значок, в ячейке не отображается значок. Но если значение сущности не указывает значок, в значении ячейки отображается значок по умолчанию.

Форматированное число

Форматирование чисел можно применить к значениям типа CellValueType.double. numberFormat Используйте свойство в схеме JSON, чтобы указать числовой формат. В следующем примере кода показана полная схема числового значения в формате валюты. Значение отформатированного числа в примере кода отображается как 24,00 долл. США в пользовательском интерфейсе 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();
    });
}

Форматирование чисел считается форматом по умолчанию. Если пользователь или другой код применяет форматирование к ячейке, содержащей отформатированный номер, примененный формат переопределяет формат номера.

Макет карточки

Значения ячеек со свойствами имеют тип данных по умолчанию карта, который может просматривать пользователь. Вы можете предоставить пользовательский макет карта, который будет использоваться вместо макета по умолчанию карта, чтобы улучшить взаимодействие с пользователем при просмотре свойств. Для этого добавьте свойство layouts в описание JSON.

Дополнительные сведения см. в разделе Использование карточек с типами данных значения ячеек.

Вложенные типы данных

Типы данных можно вложить в значение ячейки, например дополнительные значения сущностей, а также строки, двойные и логические значения. В следующем примере кода показано, как создать значение ячейки, представляющее состояние заряда на батарее компьютера. Он содержит значение вложенной сущности, описывающее свойства компьютера для потребления энергии и состояния зарядки. Значение сущности компьютера также содержит вложенное строковое значение, описывающее план управления питанием компьютера.

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

На следующем рисунке показано числовое значение и тип данных, карта для сущности вложенного ноутбука.

Совместимость

В предыдущих версиях Excel, которые не поддерживают типы данных, пользователи видят предупреждение Недоступно тип данных. Значение по-прежнему отображается в ячейке и функциях, как и ожидалось, с формулами и другими функциями Excel. Если значение является отформатированным числом, вычисления используют basicValue вместо форматированного числа.

В версиях Excel старше Office 2016 значение отображается в ячейке без ошибок и не отличается от базового значения.

См. также

• Основные понятия, связанные с типами данных API JavaScript для Excel