Использование карточек с типами данных значения ячеек

2025-05-13

Вы можете указать карта модальные окна в пользовательском интерфейсе Excel для различных типов данных значений ячеек. Карточки могут отображать дополнительные сведения, помимо уже видимых в ячейке, такие как связанные изображения, сведения о категории продуктов и атрибуты данных.

Примечание.

В этой статье рассматриваются сведения, описанные в статье Основные понятия типов данных Excel . Мы рекомендуем прочитать эту статью, прежде чем изучать карточки для значений ячеек.

Карточки поддерживаются для следующих типов значений ячеек.

EntityCellValue
LinkedEntityCellValue
базовые типы string, double и boolean

На следующем снимке экрана показан пример значения открытой сущности карта, в данном случае для продукта Chef Антона Gumbo Mix из списка продуктов продуктов продуктового магазина.

Тип данных значения сущности с отображаемым окном карта.

Свойства карточки

Используйте properties для указания всех пользовательских сведений о типах данных. Ключ properties поддерживает вложенные типы данных. Каждое вложенное свойство или тип данных должно иметь type параметр и basicValue .

Важно!

properties Вложенные типы данных используются в сочетании со значениями макета карточки, описанными в следующем разделе статьи. После определения вложенного типа данных в propertiesнеобходимо назначить его в свойстве layouts для отображения на карта.

В следующем фрагменте кода показан json для значения сущности с несколькими типами данных, вложенными в properties.

Примечание.

Чтобы поэкспериментировать с этим фрагментом кода в полном примере, откройте Script Lab в Excel и выберите Типы данных: Создание карточек сущностей из данных в таблице в библиотеке примеров.

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

На следующем снимке экрана показано значение сущности карта, использующее предыдущий фрагмент кода. На снимке экрана показаны сведения об идентификаторе продукта, названии продукта, изображении, количестве на единицу и цене за единицу из предыдущего фрагмента кода.

Тип данных значения сущности с отображаемым окном макета карта. В карта отображаются название продукта, идентификатор продукта, количество на единицу и сведения о цене за единицу.

Макет карточки

Значения ячеек имеют тип данных по умолчанию карта, который пользователь может просматривать. Укажите пользовательский макет карта, чтобы улучшить взаимодействие с пользователем при просмотре свойств. Свойство layouts определяет структуру и внешний вид карта. Используйте layouts для указания таких атрибутов, как значок, заголовок карта, изображение для карта и количество отображаемых разделов.

Важно!

layouts Вложенные значения используются в сочетании с типами данных свойств карточки, описанными в предыдущем разделе статьи. Вложенный тип данных должен быть определен в properties , прежде чем его можно будет назначить в layouts для отображения на карта.

Свойство layouts содержит два прямых вложенных свойства: compact и card. Свойство card указывает внешний вид карта при открытии карта. Свойство compact является необязательным и определяет значок для значения. Значок отображается в значении ячейки, если он указан. Он также может отображаться в карта, если на него ссылается подсвойство.

Полный EntityCompactLayoutIcons список доступных значков см. в перечислении. В следующем фрагменте кода показано, как отобразить shoppingBag значок.

В свойстве card используйте CardLayoutStandardProperties объект для определения компонентов карта, таких как title, subTitleи sections.

Json значения сущности в следующем фрагменте кода показывает card макет со вложенными объектами title и mainImage , а также тремя sections объектами в карта. Обратите внимание, что свойство title"Product Name" имеет соответствующий тип данных в предыдущем разделе свойства карточки . Свойство mainImage также имеет соответствующий "Image" тип данных в предыдущем разделе. Свойство sections принимает вложенный массив и использует CardLayoutSectionStandardProperties объект для определения внешнего вида каждого раздела.

В каждом разделе карта можно указать такие элементы, как layout, titleи properties. Ключ layout использует CardLayoutListSection объект и принимает значение "List". Ключ properties принимает массив строк. Обратите внимание, что properties значения, такие как "Product ID", имеют соответствующие типы данных в предыдущем разделе свойств карточки . Разделы также могут быть сворачиваемыми и могут быть определены с помощью логических значений как свернутые или не свернутые при открытии сущности карта в пользовательском интерфейсе Excel.

Совет

Ключ layout также имеет дополнительные параметры отображения, доступные за пределами "List" карта разделов. Используйте "Table" для Excel.CardLayoutTableSection и "TwoColumn"Excel.CardLayoutTwoColumnSection. Обратите внимание, что "TwoColumn" макет доступен только в предварительной версии.

Примечание.

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 объект , который использует название продукта и имеет значение Gumbo Mix шеф-повара Антона. На снимку экрана также показана sections. Раздел "Количество и цена " является сворачиваемым и содержит количество на единицу и цену за единицу. Поле Дополнительные сведения свертываемо и сворачивается при открытии карта.

Тип данных значения сущности с отображаемым окном макета карта. В карта отображаются заголовок и разделы карта.

Примечание.

На предыдущем снимке экрана branch значок отображается рядом с приправами в разделе Категория . Сведения о настройке вложенных значков, таких как значок раздела "Категория", см. в статье Типы данных: создание карточек сущностей из данных в таблице.

Существует известная проблема со вложенными значками в Excel на Mac. В этой среде вложенные значки всегда будут отображаться как 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.CellValueAttributionAttributes для добавления атрибутов к значению ячейки. В следующем примере кода показано, как добавить атрибуты для использования сведений о планете Марс из Википедии.

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.

Дальнейшие действия

Ознакомьтесь с примером создание и изучение типов данных в Excel в репозитории OfficeDev/Office-Add-in-samples . В этом примере описывается создание и загрузка неопубликованного приложения, которая создает и изменяет типы данных в книге.

Поделиться через

Использование карточек с типами данных значения ячеек

Свойства карточки

Макет карточки

Метаданные свойства

Приписывание

Сведения о поставщике

Дальнейшие действия

См. также

Дополнительные ресурсы