Основные понятия, связанные с типами данных 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 для типов форматированного числа, сущности и веб-изображения.

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

Объект DoubleCellValue позволяет надстройкам 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.DoubleCellValue = {
    type: Excel.CellValueType.double,
    basicValue: 32889.0,
    basicType: Excel.RangeValueType.double, // A read-only property. Used as a fallback in incompatible scenarios.
    numberFormat: "m/d/yyyy"
};

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

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

Базовые значения ячеек

Добавьте свойства к базовым значениям ячеек в Excel, чтобы связать дополнительные сведения со значениями. Как и значения сущностей, можно добавлять свойства к базовым типам string, double и boolean . Каждое свойство является парой "ключ-значение". В следующем примере показано число 104,67 (двойник), представляющее счет с добавленными полями с именами "Напитки", "Еда", "Налог" и "Чаевые".

Снимок экрана: поля напитков, продуктов питания, налогов и чаевых для выбранного значения ячейки.

Дополнительные сведения см. в разделе Добавление свойств к базовым значениям ячейки.

Сущность

Значение сущности — это контейнер для типов данных, аналогичный объекту в объектно-ориентированном программировании. Сущности также поддерживают массивы в качестве свойств значения сущности. Объект 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.
};

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

Значения ячеек связанной сущности

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

Значения ячеек связанной сущности связаны с внешним источником данных. Они предоставляют следующие преимущества по сравнению с обычными значениями сущностей:

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

См. также

Обратная связь

Была ли эта страница полезна?

Last updated on 2025-05-13