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

Статья
03/10/2023

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

Примечание.

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

Значение сущности, или EntityCellValue, — это контейнер для типов данных, аналогичный объекту объектно-ориентированного программирования. В этой статье показано, как использовать значение сущности карта свойствами, параметрами макета и функциями атрибуции данных для создания значений сущностей, отображаемых в виде карточек.

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

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

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

Свойство entity value 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.formattedNumber,
            basicValue: product.unitPrice,
            numberFormat: "$* #,##0.00"
        },
        Discontinued: {
            type: Excel.CellValueType.boolean,
            basicValue: product.discontinued || false
        }
    },
    layouts: {
        // Enter layout settings here.
    }
};

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

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

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

Свойства сущности имеют необязательное 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.formattedNumber,
            basicValue: product.unitPrice,
            numberFormat: "$* #,##0.00",
            propertyMetadata: {
              sublabel: "USD"
            }
        },

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

Вложенная метка USD рядом с полем Цена за единицу.

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

Свойство entity value 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.

Примечание.

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 .

Присвоение данных карточки

Карточки значений сущности могут отображать присвоение данных, чтобы предоставить кредит поставщику информации в сущности карта. Свойство entity value provider использует CellValueProviderAttributes объект , который определяет descriptionзначения , logoSourceAddressи logoTargetAddress .

Свойство поставщика данных отображает изображение в левом нижнем углу карта сущности. Он использует , logoSourceAddress чтобы указать исходный URL-адрес для изображения. Значение logoTargetAddress определяет назначение URL-адреса, если выбрано изображение логотипа. Значение description отображается в виде подсказки при наведении указателя мыши на логотип. Значение description также отображается в виде резервного простого текста, logoSourceAddress если значение не определено или если исходный адрес для изображения поврежден.

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

Примечание.

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

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

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

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

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

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

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

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

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

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

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

Присвоение данных карточки

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

См. также

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