Excel 数据类型核心概念

  • 项目

本文介绍如何使用 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 代码示例。

带格式数字值

FormattedNumberCellValue 对象使 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.FormattedNumberCellValue = {
    type: Excel.CellValueType.formattedNumber,
    basicValue: 32889.0,
    basicType: Excel.RangeValueType.double, // A read-only property. Used as a fallback in incompatible scenarios.
    numberFormat: "m/d/yyyy"
};

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

实体值

实体值是数据类型的容器，类似于面向对象的编程中的对象。 实体还支持数组作为实体值的属性。 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.
};

实体值还提供可创建实体的卡片的 layouts 属性。 该卡片在 Excel UI 中显示为模式窗口，并且可以显示实体值中包含的其他信息，而不仅显示单元格中可见的信息。 要了解详细信息，请参阅 使用具有实体值数据类型的卡片。

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

已链接实体

已链接实体值或 LinkedEntityCellValue 对象是实体值的一种类型。 这些对象集成外部服务提供的数据，并可以将此数据显示为实体卡片，例如常规实体值。 通过 Excel UI 提供的股票和地理位置数据类型是已链接实体值。

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.
};

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

改进的错误支持

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

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

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

通过查看脚本实验室示例库中的“数据类型：设置错误值”片段，详细了解数据类型错误对象。

后续步骤

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

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

另请参阅