使用具有实体值数据类型的卡片

本文介绍如何使用 Excel JavaScript API 在 Excel UI 中创建具有实体值数据类型的卡模式窗口。 这些卡片可以显示实体值中包含的其他信息，超出单元格中已可见的信息，例如相关图像、产品类别信息和数据属性。

实体值或 EntityCellValue 是数据类型的容器，类似于面向对象的编程中的对象。 本文介绍如何使用实体值卡属性、布局选项和数据归属功能来创建显示为卡片的实体值。

以下屏幕截图显示了一个打开实体值卡的示例，在本例中为来自杂货店产品列表中的 Chef Anton's Gumbo Mix 产品。

卡片属性

实体值 properties 属性允许设置有关数据类型的自定义信息。 密钥 properties 接受嵌套数据类型。 每个嵌套属性或数据类型都必须具有 type 和 basicValue 设置。

以下代码片段显示了实体值的 JSON，其中嵌套了 properties多个数据类型。

const entity: Excel.EntityCellValue = {
    type: Excel.CellValueType.entity,
    text: productName,
    properties: {
        "Product ID": {
            type: Excel.CellValueType.string,
            basicValue: productID.toString() || ""
        },
        "Product Name": {
            type: Excel.CellValueType.string,
            basicValue: productName || ""
        },
        "Image": {
            type: Excel.CellValueType.webImage,
            address: product.productImage || ""
        },
        "Quantity Per Unit": {
            type: Excel.CellValueType.string,
            basicValue: product.quantityPerUnit || ""
        },
        "Unit Price": {
            type: Excel.CellValueType.formattedNumber,
            basicValue: product.unitPrice,
            numberFormat: "$* #,##0.00"
        },
        Discontinued: {
            type: Excel.CellValueType.boolean,
            basicValue: product.discontinued || false
        }
    },
    layouts: {
        // Enter layout settings here.
    }
};

以下屏幕截图显示了使用上述代码片段的实体值卡。 屏幕截图显示了上述代码片段中的 “产品 ID”、“ 产品名称”、“ 图像”、“ 每单位数量”和“ 单价 ”信息。

属性元数据

实体属性具有一个可选 propertyMetadata 字段，该字段使用 CellValuePropertyMetadata 对象并提供属性 attribution、 excludeFrom和 sublabel。 以下代码片段演示如何将 添加到 sublabel 上述代码片段中的 "Unit Price" 属性。 在这种情况下，子标签标识货币类型。

// This code snippet is an excerpt from the `properties` field of the 
// preceding `EntityCellValue` snippet. "Unit Price" is a property of 
// an entity value.
        "Unit Price": {
            type: Excel.CellValueType.formattedNumber,
            basicValue: product.unitPrice,
            numberFormat: "$* #,##0.00",
            propertyMetadata: {
              sublabel: "USD"
            }
        },

以下屏幕截图显示了使用上述代码片段的实体值卡，其中显示了“单价”属性旁边的 USD 属性元数据sublabel。

卡片布局

实体值 layouts 属性定义实体的外观。 用于layouts指定属性，例如实体图标、卡标题、卡的图像以及要显示的节数。

属性 layouts 包含两个直接子属性 compact 和 card。 属性card指定打开实体卡时卡的外观。 属性compact仅定义实体的图标，仅当卡处于压缩或未打开状态时才显示此图标。 有关可用图标的完整列表， EntityCompactLayoutIcons 请参阅枚举。 下一个代码片段演示如何显示图标 shoppingBag 。

在 属性中card，使用 CardLayoutStandardProperties 对象定义 卡的组件，如 title、 subTitle和 sections。

下一个代码片段中的实体值 JSON 显示一个card包含嵌套title和 mainImage 对象的布局，以及卡中的三个sections。 请注意， title 属性 "Product Name" 在前面的 Card 属性 文章部分中具有相应的数据类型。 属性 mainImage 在上一节中也具有相应的 "Image" 数据类型。 属性 sections 采用嵌套数组，并使用 CardLayoutSectionStandardProperties 对象定义每个部分的外观。

在每个卡节中，可以指定 、 title和 properties等layout元素。 键 layout 使用 CardLayoutListSection 对象并接受值 "List"。 键 properties 接受字符串数组。 请注意， properties 值（如 "Product ID"）在前面的 Card 属性 文章部分中具有相应的数据类型。 在 Excel UI 中打开实体卡时，节也可以是可折叠的，并且可以使用布尔值定义为折叠或不折叠。

const entity: Excel.EntityCellValue = {
    type: Excel.CellValueType.entity,
    text: productName,
    properties: {
        // Enter property settings here.
    },
    layouts: {
        compact: {
            icon: Excel.EntityCompactLayoutIcons.shoppingBag
        },
        card: {
            title: { 
                property: "Product Name" 
            },
            mainImage: { 
                property: "Image" 
            },
            sections: [
                {
                    layout: "List",
                    properties: ["Product ID"]
                },
                {
                    layout: "List",
                    title: "Quantity and price",
                    collapsible: true,
                    collapsed: false, // This section will not be collapsed when the card is opened.
                    properties: ["Quantity Per Unit", "Unit Price"]
                },
                {
                    layout: "List",
                    title: "Additional information",
                    collapsible: true,
                    collapsed: true, // This section will be collapsed when the card is opened.
                    properties: ["Discontinued"]
                }
            ]
        }
    }
};

以下屏幕截图显示了使用上述代码片段的实体值卡。 在屏幕截图中 shoppingBag ，图标与电子表格中的产品名称一起显示。 在实体卡中，mainImage对象显示在顶部，后跟title使用产品名称并设置为 Chef Anton's Gumbo Mix 的对象。 屏幕截图还显示了 sections。 “ 数量和价格 ”部分可折叠，包含 “按单位数量 ”和“ 单价”。 “其他信息”字段可折叠，并在打开卡时折叠。

卡片数据归属

实体价值卡可以显示数据属性，以便向实体卡中信息的提供者提供信用。 实体值 provider 属性使用 CellValueProviderAttributes 对象，该对象定义 description、 logoSourceAddress和 logoTargetAddress 值。

数据提供程序属性在实体卡的左下角显示图像。 它使用 logoSourceAddress 指定图像的源 URL。 如果选择徽标图像，则 logoTargetAddress 值定义 URL 目标。 将 description 鼠标悬停在徽标上时，该值显示为工具提示。 如果未logoSourceAddress定义 或图像的源地址中断，则description该值还会显示为纯文本回退。

以下代码片段中的 JSON 显示了一个实体值，该值使用 provider 属性为实体指定数据提供程序属性。

const entity: Excel.EntityCellValue = {
    type: Excel.CellValueType.entity,
    text: productName,
    properties: {
        // Enter property settings here.
    },
    layouts: {
        // Enter layout settings here.
    },
    provider: {
        description: product.providerName, // Name of the data provider. Displays as a tooltip when hovering over the logo. Also displays as a fallback if the source address for the image is broken.
        logoSourceAddress: product.sourceAddress, // Source URL of the logo to display.
        logoTargetAddress: product.targetAddress // Destination URL that the logo navigates to when selected.
    }
};

以下屏幕截图显示了使用上述代码片段的实体值卡。 屏幕截图显示了左下角的数据提供程序属性。 在此实例中，数据提供程序为 Microsoft，并显示 Microsoft 徽标。

后续步骤

试用 OfficeDev/Office-Add-in-samples 存储库中的“在 Excel 中创建和浏览数据类型”示例。 此示例将指导你生成和旁加载加载项，该加载项在工作簿中创建和编辑数据类型。

另请参阅

• Excel 加载项中的数据类型的概述
• Excel 数据类型核心概念
• 在 Excel 中创建和浏览数据类型
• Excel JavaScript API 参考