将卡片与单元格值数据类型配合使用

2025-05-13

可以在 Excel UI 中为各种单元格值数据类型指定卡模式窗口。卡片可以显示单元格中已可见内容以外的其他信息，例如相关图像、产品类别信息和数据属性。

注意

本文扩展了 Excel 数据类型核心概念一文中所述的信息。建议在了解单元格值的卡片之前阅读该文章。

以下单元格值类型支持卡片。

EntityCellValue
LinkedEntityCellValue
string、 double 和 Boolean 基本类型

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

显示卡窗口的实体值数据类型。

卡片属性

使用 properties 指定有关数据类型的所有自定义信息。键 properties 支持嵌套数据类型。每个嵌套属性或数据类型都必须具有 type 和 basicValue 设置。

重要

嵌套 properties 数据类型与后续文章部分所述的卡片布局值结合使用。在中properties定义嵌套数据类型后，必须在属性中layouts分配它才能显示在卡。

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

注意

若要在完整示例中试验此代码片段，请在 Excel 中打开Script Lab，然后选择“数据类型：从示例库”表中的数据创建实体卡。

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.double,
            basicValue: product.unitPrice,
            numberFormat: "$* #,##0.00"
        },
        Discontinued: {
            type: Excel.CellValueType.boolean,
            basicValue: product.discontinued || false
        }
    },
    layouts: {
        // Enter layout settings here.
    }
};

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

显示卡布局窗口的实体值数据类型。卡显示产品名称、产品 ID、单位数量和单价信息。

卡片布局

单元格值具有用户可以查看的默认数据类型卡。指定自定义卡布局，以改善查看属性时的用户体验。属性layouts定义卡的结构和外观。用于layouts指定图标、卡标题、卡的图像和要显示的节数等属性。

重要

嵌套 layouts 值与上一篇文章部分所述的 Card 属性数据类型结合使用。必须先在中properties定义嵌套数据类型，然后才能将其分配给 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 中打开实体卡时，节也可以是可折叠的，并且可以使用布尔值定义为折叠或不折叠。

注意

若要在完整示例中试验此代码片段，请在 Excel 中打开Script Lab，然后选择“数据类型：从示例库”表中的数据创建实体卡。

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。 “ 数量和价格 ”部分可折叠，包含 “按单位数量 ”和“ 单价”。 “其他信息”字段可折叠，并在打开卡时折叠。

显示卡布局窗口的实体值数据类型。卡显示卡标题和节。

注意

在前面的屏幕截图中，图标与branch“类别”部分中的“调味品”一起显示。请参阅数据类型：从表中的数据创建实体卡示例，了解如何设置嵌套图标，如 “类别 ”部分图标。

Mac 版 Excel 中的嵌套图标存在一个已知问题。在该环境中，嵌套图标将始终显示为 generic 图标，无论使用枚举选择了 EntityCompactLayoutIcons 哪个图标。

属性元数据

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

注意

字段 propertyMetadata 仅适用于嵌套在实体属性中的数据类型。

// 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.double,
        basicValue: product.unitPrice,
        numberFormat: "$* #,##0.00",
        propertyMetadata: {
          sublabel: "USD"
        }
    },

归因

为来自第三方的信息添加属性，以指示源和任何许可证信息。使用 Excel.CellValueAttributionAttributionAttributes 向单元格值添加属性。下面的代码示例演示如何添加属性，以便使用维基百科中有关火星的信息。

async function createPlanet() {
    await Excel.run(async (context) => {
        const sheet = context.workbook.worksheets.getActiveWorksheet();
        const range = sheet.getRange("A1");
        const attributionObject: Excel.CellValueAttributionAttributes = {
            licenseAddress: "https://en.wikipedia.org/wiki/Wikipedia:Wikipedia_is_free_content",
            licenseText: "Free usage information",
            sourceAddress: "https://en.wikipedia.org/wiki/Mars",
            sourceText: "Wikipedia"
        };

        range.valuesAsJson = [
            [
                {
                    type: Excel.CellValueType.double,
                    basicType: Excel.RangeValueType.double,
                    basicValue: 6779, // kilometers (radius)
                    properties: {
                        Name: {
                            type: Excel.CellValueType.string,
                            basicType: Excel.RangeValueType.string,
                            basicValue: "Mars",
                            propertyMetadata: {
                                sublabel: "Planetary Body",
                                attribution: [attributionObject]
                            }
                        }
                    }
                }
            ]
        ];
        await context.sync();
    });
}

下图显示了用户数据类型卡属性的显示方式。

显示维基百科属性的数据类型卡。

提供程序信息

可以添加有关外接程序或服务的信息，这是数据类型卡中信息的源。使用 Excel.CellValueProviderAttributes 添加提供程序信息。以下代码示例演示如何将 Contoso 泛型搜索的提供程序信息添加为单元格值的搜索数据源。

async function createSearchEntry() {
    await Excel.run(async (context) => {
        const sheet = context.workbook.worksheets.getActiveWorksheet();
        const range = sheet.getRange("A1");

        range.valuesAsJson = [
            [
                {
                    type: Excel.CellValueType.string,
                    basicType: Excel.RangeValueType.string,
                    basicValue: "cell function - Microsoft support",
                    properties: {
                        "Search Keywords": {
                            type: Excel.CellValueType.string,
                            basicType: Excel.RangeValueType.string,
                            basicValue: "Cell Values"
                        }
                    },
                    provider: {
                        description: "Contoso generic search",
                        // Image credit: Ignacio javier igjav, Public ___domain, via Wikimedia Commons
                        logoSourceAddress: "https://upload.wikimedia.org/wikipedia/commons/f/f9/Lupa.png",
                        logoTargetAddress: "https://contoso.com"
                    }
                }
            ]
        ];

        await context.sync();
    });
}

下图显示了提供程序信息在用户数据类型卡中作为徽标的显示方式。

数据类型卡显示 Contoso 泛型搜索的搜索徽标。

后续步骤

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

通过