Основные понятия, связанные с типами данных Excel

  • Статья

В этой статье рассказывается о том, как использовать API JavaScript для Excel для работы с типами данных. Здесь представлены основные понятия, лежащие в основе разработки типов данных.

Свойство valuesAsJson.

Свойство valuesAsJson (или единственное число valueAsJson для NamedItem) является неотъемлемой частью создания типов данных в Excel. Это свойство является расширением свойств values, таких как Range.values. Оба свойства values и valuesAsJson используются для доступа к значению в ячейке, но свойство values возвращает только один из четырех основных типов: строка, число, логическое значение или ошибка (в виде строки). Напротив, свойство valuesAsJson возвращает расширенную информацию об этих четырех основных типах, а также такие типы данных, как форматированное число, сущность и веб-изображение.

Следующие объекты предлагают свойство valuesAsJson.

Примечание.

Некоторые значения ячеек изменяются в зависимости от языкового стандарта пользователя. Свойство valuesAsJsonLocal предлагает поддержку локализации и доступно для всех тех же объектов, что и valuesAsJson.

Значения ячеек

Свойство valuesAsJson возвращает псевдоним типа CellValue, который является объединением следующих типов данных.

Псевдоним типа CellValue также возвращает объект CellValueExtraProperties, который является пересечением с остальными *CellValue типами. Это не тип данных. Свойства объекта CellValueExtraProperties используются со всеми типами данных для указания сведений, связанных с перезаписью значений ячеек.

Схема JSON

Каждый тип значения ячейки, возвращаемый valuesAsJson, использует схему метаданных JSON, разработанную для этого типа. Наряду с дополнительными свойствами, уникальными для каждого типа данных, все эти схемы метаданных JSON имеют общие свойства type, basicType, и basicValue

Определяет typecellValueType данных. Объект basicType всегда доступен только для чтения и используется в качестве резервного, если тип данных не поддерживается или неправильно отформатирован. basicValue соответствует значению, которое будет возвращено свойством values. basicValue используется в качестве запасного варианта, когда расчеты сталкиваются с несовместимыми сценариями, такими как более старая версия Excel, не поддерживающая функцию типов данных. Объект basicValue доступен только для чтения для ArrayCellValueтипов данных , EntityCellValue, LinkedEntityCellValueи WebImageCellValue .

В дополнение к трем полям, общим для всех типов данных, схема метаданных JSON для каждого *CellValue имеет свойства, доступные в соответствии с этим типом. Например, тип WebImageCellValue включает свойства altText и attribution, а тип EntityCellValue предлагает поля properties и text.

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

Форматированное число

Объект FormattedNumberCellValue позволяет настройкам Excel определять свойство numberFormat для некоторого значения. После того как свойство форматированного числа присвоено значению, оно сопровождает это значение в расчетах и может возвращаться функциями.

В следующем примере кода JSON показана полная схема значения форматированного числа. Значение форматированного числа myDate в примере кода отображается в пользовательском интерфейсе Excel как 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"
};

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

Сущность

Значение сущности — это контейнер для типов данных, аналогичный объекту в объектно-ориентированном программировании. Сущности также поддерживают массивы в качестве свойств значения сущности. Объект EntityCellValue позволяет надстройкам определять такие свойства, как type, text и properties. Свойство properties позволяет значению сущности определять и содержать дополнительные типы данных.

Свойства basicType и basicValue определяют, как вычисления читают этот тип данных сущности, если минимальные требования к совместимости для использования типов данных не выполнены. В этом сценарии этот тип данных сущности отображается как ошибка #VALUE! в пользовательском интерфейсе Excel.

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

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

Связанные объекты

Значения связанных сущностей или объекты LinkedEntityCellValue являются типом значения сущности. Эти объекты интегрируют данные, предоставленные внешней службой, и могут отображать эти данные в виде карты сущности, как обычные значения сущности. Типы данных Stocks и Geography, доступные через пользовательский интерфейс Excel, являются значениями связанных сущностей.

Веб-изображение

Объект WebImageCellValue создает возможность хранения изображения как части сущности или как независимого значения в диапазоне. Этот объект позволяет использовать множество свойств, включая address, altText и relatedImagesAddress.

Свойства basicType и basicValue определяют, как вычисления читают этот тип данных веб-изображения, если минимальные требования к совместимости для использования функции типов данных не выполнены. В этом сценарии этот тип данных веб-изображения отображается как ошибка #VALUE! в пользовательском интерфейсе Excel.

В следующем примере кода JSON показана полная схема веб-изображения.

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

Опробуйте типы данных веб-изображений, открыв Script Lab и выбрав фрагмент фрагмента Типы данных: веб-изображения в библиотеке Примеры.

Улучшенная поддержка ошибок

API типов данных представляют существующие ошибки пользовательского интерфейса Excel в качестве объектов. Теперь, когда эти ошибки доступны как объекты, надстройки могут определять или извлекать такие свойства, как type, errorType и errorSubType.

Ниже приводится список всех объектов ошибок с поддержкой, расширенной за счет типов данных.

Каждый из объектов ошибок может получить доступ к перечисление через свойство errorSubType, и в этом перечислении содержатся дополнительные данные об ошибке. Например, объект ошибки BlockedErrorCellValue может получить доступ к перечислению BlockedErrorCellValueSubType. В перечислении BlockedErrorCellValueSubType содержатся дополнительные данные о том, что вызвало данную ошибку.

Дополнительные сведения об объектах ошибок типов данных см. в статье Типы данных: задание значений ошибок в библиотеке Script LabSamples.

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

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

Используйте пример Создание и изучение типов данных в Excel в репозитории OfficeDev/Office-Надстройка в примерах , чтобы более глубоко поэкспериментировать с типами данных, создавая и загружая неопубликованные надстройки, которые создают и редактируют типы данных в книге.

См. также