Excel 数据类型核心概念

2025-05-13

本文介绍如何使用 Excel JavaScript API 来处理数据类型。它引入了对数据类型开发至关重要的核心概念。

`valuesAsJson` 属性

NamedItemvaluesAsJson) 的属性 (或单数valueAsJson是 Excel 中创建数据类型不可或缺的一部分。此属性是 values 属性的扩展，例如 Range.values。 values 和 valuesAsJson 属性都用于访问单元格中的值，但 values 属性仅返回以下四种基本类型之一：字符串、数字、布尔或错误（作为字符串）。对比来看，valuesAsJson 返回有关这四种基本类型的扩展信息，并且此属性可以返回数据类型，例如带格式的数值、实体和 Web 图像。

以下对象提供 valuesAsJson 属性。

注意

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

单元格值

valuesAsJson 属性返回 CellValue 类型别名，而这是以下数据类型的联合。

CellValue 类型别名还返回 CellValueExtraProperties 对象，这是和 *CellValue 类型其余部分的交集。它本身不是数据类型。 CellValueExtraProperties 对象的属性与所有数据类型一起使用，用于指定与覆盖单元格值相关的详细信息。

JSON 架构

valuesAsJson 返回的每个单元格值类型使用为该类型设计的 JSON 元数据架构。除了每个数据类型特有的附加属性，这些 JSON 元数据架构都具有共同的 type、basicType 和 basicValue 属性。

type 定义数据的 CellValueType。始终 basicType 是只读的，在数据类型不受支持或格式不正确时用作回退。 basicValue 与将由 values 属性返回的值匹配。 basicValue 在计算遇到不兼容方案时用作回退，例如不支持数据类型功能的较旧版本的 Excel。 basicValue对于、、 EntityCellValueLinkedEntityCellValue和 WebImageCellValue 数据类型，是ArrayCellValue只读的。

除了所有数据类型共享的三个字段之外，每个 *CellValue 的 JSON 元数据架构都有根据该类型的可用属性。例如，WebImageCellValue 类型包括 altText 和 attribution 属性，而 EntityCellValue 类型则提供 properties 和 text 字段。

以下部分显示带格式数字值、实体值和 Web 图像数据类型的 JSON 代码示例。

带格式数字值

DoubleCellValue 对象使 Excel 加载项能够定义numberFormat值的属性。分配后，此数字格式将使用该值进行计算，并可由函数返回。

以下 JSON 代码示例显示了格式化数字值的完整架构。代码示例中的 myDate 带格式数字值在 Excel UI 中显示为 1/16/1990。如果不满足数据类型功能的最低兼容性要求，则计算使用 basicValue 代替格式化的数字。

// This is an example of the complete JSON of a formatted number value.
// In this case, the number is formatted as a date.
const myDate: Excel.DoubleCellValue = {
    type: Excel.CellValueType.double,
    basicValue: 32889.0,
    basicType: Excel.RangeValueType.double, // A read-only property. Used as a fallback in incompatible scenarios.
    numberFormat: "m/d/yyyy"
};

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

通过打开Script Lab并签出示例库中的“数据类型：格式化数字”代码片段，开始试验格式化的数字值。

基本单元格值

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

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

有关详细信息，请参阅向基本单元格值添加属性。

实体值

实体值是数据类型的容器，类似于面向对象的编程中的对象。实体还支持数组作为实体值的属性。 EntityCellValue 对象允许加载项定义属性，如 type、text 和 properties。 properties 属性使实体值能够定义并包含其他数据类型。

basicType 和 basicValue 属性定义了如果未满足使用数据类型的最低兼容性要求，计算将如何读取此实体数据类型。在这种情况下，此实体数据类型在 Excel UI 中显示为 #VALUE！ 错误。

以下 JSON 代码示例显示了包含文本、图像、日期和其他文本值的实体值的完整架构。

// This is an example of the complete JSON for an entity value.
// The entity contains text and properties which contain an image, a date, and another text value.
const myEntity: Excel.EntityCellValue = {
    type: Excel.CellValueType.entity,
    text: "A llama",
    properties: {
        image: myImage,
        "start date": myDate,
        "quote": {
            type: Excel.CellValueType.string,
            basicValue: "I love llamas."
        }
    }, 
    basicType: Excel.RangeValueType.error, // A read-only property. Used as a fallback in incompatible scenarios.
    basicValue: "#VALUE!" // A read-only property. Used as a fallback in incompatible scenarios.
};

若要浏览实体数据类型，请先转到 Excel 中的Script Lab，然后打开“数据类型：从示例库的表片段中的数据创建实体卡片”。 “数据类型：包含引用的实体值”和“数据类型：实体值”属性代码段提供了对实体特征的更深入的了解。

链接的实体单元格值

链接实体单元格值或 LinkedEntityCellValue 对象是外部数据源的集成数据类型，可以将数据显示为实体卡。借助它们，你可以缩放数据类型以表示大型数据集，而无需将所有数据下载到工作簿中。通过 Excel UI 提供的 “股票”和“地理”数据域提供链接的实体单元格值。

链接的实体单元格值链接到外部数据源。与常规实体值一样，它们具有以下优势：

链接实体单元格值可以嵌套，在用户或工作表引用之前，不会检索嵌套链接实体单元格值。这有助于减小文件大小并提高工作簿性能。
Excel 使用缓存允许不同的单元格无缝引用相同的链接实体单元格值。这还可以提高工作簿性能。

有关详细信息，请参阅创建链接实体单元格值。

Web 图像值

WebImageCellValue 对象创建将图像存储为实体或作为区域中独立值的一部分的功能。此对象提供许多属性，包括 address、altText 和 relatedImagesAddress。

basicType 和 basicValue属性定义了如果未满足使用数据类型功能的最低兼容性要求，计算将如何读取 Web 图像数据类型。在这种情况下，此 Web 图像数据类型在 Excel UI 中显示为 #VALUE！ 错误。

以下 JSON 代码示例显示了 Web 图像的完整架构。

// This is an example of the complete JSON for a web image.
const myImage: Excel.WebImageCellValue = {
    type: Excel.CellValueType.webImage,
    address: "https://bit.ly/2YGOwtw", 
    basicType: Excel.RangeValueType.error, // A read-only property. Used as a fallback in incompatible scenarios.
    basicValue: "#VALUE!" // A read-only property. Used as a fallback in incompatible scenarios.
};

通过打开Script Lab并选择示例库中的“数据类型：Web 图像”片段来试用 Web 图像数据类型。

改进的错误支持

数据类型 API 将现有 Excel UI 错误公开为对象。现在，因为这些错误可作为对象访问，加载项就可以定义或检索属性，如 type、errorType 和 errorSubType。

下面是通过数据类型扩展支持的所有错误对象的列表。

每个错误对象都可以通过 errorSubType 属性访问枚举，并且此枚举包含有关错误的其他数据。例如，BlockedErrorCellValue 错误对象可以访问 BlockedErrorCellValueSubType 枚举。 BlockedErrorCellValueSubType 枚举提供有关导致错误原因的其他数据。

通过查看 Script LabSamples 库中的“数据类型：设置错误值”片段，详细了解数据类型错误对象。

后续步骤

通过使用实体值数据类型的卡片一文，了解实体数据类型如何将 Excel 加载项的潜力扩展到 2 维网格之外。

使用 OfficeDev/Office-Add-in-samples 存储库中的“在 Excel 中创建和浏览数据类型”示例，通过生成和旁加载在工作簿中创建和编辑数据类型的外接程序，更深入地试验数据类型。

通过