向基本单元格值添加属性

2025-05-13

在 Excel 中向基本单元格值添加属性，以将其他信息与值相关联。与实体值类似，可以向 字符串、 double 和布尔基本类型添加属性。每个属性都是键/值对。以下示例显示数字 14.67 (一个双) ，该) 表示具有名为 “饮料”、“ 食品”、“ 税务”和 “小费”的添加字段的帐单。

为所选单元格值显示的饮料、食品、税收和小费字段的屏幕截图。

如果用户选择卡显示数据类型，他们将看到字段的值。

数据类型卡显示饮料、食品、税收和小费属性的值。

单元格值属性也可用于公式。

显示用户键入“a1.”，Excel 显示包含饮料、食品、税务和小费选项的菜单。

创建具有属性的单元格值

若要创建单元格值并向其添加属性，请使用 Range.valuesAsJson 分配属性。以下代码示例演示如何在单元格 A1 中创建新数字。它添加了食品、饮料和其他属性，用于描述餐馆中的帐单。它将属性的 JSON 说明分配给 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();
  });
}

注意

某些单元格值会根据用户的区域设置而更改。 valuesAsJsonLocal 属性提供本地化支持，并且可用于与 valuesAsJson 相同的所有对象。

向现有值添加属性

若要向现有值添加属性，请先使用 valuesAsJson从单元格获取值，然后向其添加属性 JSON 对象。以下示例演示如何从单元格 A1 获取数字值，并为其分配名为 Precision 的属性。请注意，应检查值的类型，以确保它是字符串、double 或布尔基本类型。

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

与实体值的差异

向 字符串、布尔值和 双精度 基本类型添加属性类似于向实体值添加属性。但是，存在差异。

基本类型具有非错误回退，以便可以对其执行计算。例如，假设公式 =SUM (A1：A3) 其中 A1 为 1，A2 为 2，A3 为 3。 A1 是具有属性的双精度值，而 A2 和 A3 没有属性。求和返回正确结果 6。如果 A1 是实体值，则公式将不起作用。
在计算中使用基本类型的值时，结果中将排除属性。在前面的 =SUM (A1：A3) 其中 A1 是具有属性的双精度值， 6 的结果没有任何属性。
如果未为基本类型指定任何图标，则单元格不显示任何图标。但是，如果实体值未指定图标，则会在单元格值中显示默认图标。

带格式数字值

可以将数字格式应用于类型的 CellValueType.double值。 numberFormat使用 JSON 架构中的属性指定数字格式。下面的代码示例显示了格式为货币的数字值的完整架构。代码示例中的格式化数字值在 Excel UI 中显示为 $24.00 。

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

数字格式被视为默认格式。如果用户或其他代码将格式应用于包含带格式数字的单元格，则应用的格式将覆盖该数字的格式。

卡片布局

具有属性的单元格值具有用户可以查看的默认数据类型卡。可以提供自定义卡布局，而不是默认卡布局，以改善查看属性时的用户体验。为此，请将布局属性添加到 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 中的单元格值显示电池电量为 70%，数据类型卡显示具有充电和功耗属性值的嵌套笔记本电脑实体。

兼容性

在不支持数据类型功能的早期版本的 Excel 上，用户会看到“ 数据类型不可用”警告。值仍按预期显示在单元格和函数中，并包含公式和其他 Excel 功能。如果值是带格式的数字，则计算使用代替 basicValue 带格式的数字。

在 Office 2016 之前的 Excel 版本中，该值显示在单元格中，没有错误，并且无法与基本值区分。

另请参阅

Excel JavaScript API 数据类型核心概念

通过