Общая объектная модель API JavaScript

Важно!

Эта статья относится к общим API, модели Office JavaScript API, которая появилась в Office 2013. Эти API-интерфейсы включают такие компоненты, как пользовательский интерфейс, диалоговые окна и параметры клиентов, общие для нескольких типов приложений Office. Надстройки Outlook используют только общие API, в частности подмножество API, предоставленных в объекте Mailbox.

Вы должны использовать общие API только в сценариях, которые не поддерживаются API-интерфейсами для определенных приложений. Сведения о том, как использовать общие API вместо API для определенных приложений, см. в статье Общие сведения об API JavaScript для Office.

API JavaScript Office предоставляют доступ к базовым функциям клиентского приложения Office. В основном такой доступ осуществляется при помощи нескольких значимых объектов. Объект Context предоставляет доступ к среде выполнения после инициализации. Объект Document предоставляет пользователю управление документом Excel, PowerPoint или Word. Объект почтового ящика предоставляет надстройке Outlook доступ к сообщениям, встречам и профилям пользователей. Понимание отношений между этими объектами высокого уровня лежит в основе работы надстройки Office.

Объект Context

Область применения: все типы надстроек

При инициализации надстройки она получает доступ к множеству различных объектов в среде выполнения. Объект Context отражает контекст времени выполнения надстройки в API. Контекст — это основной объект, который предоставляет доступ к наиболее важным объектам API, таким как объекты Document и Mailbox. Эти объекты предоставляют доступ к документам и содержимому почтовых ящиков.

Например, в надстройках области задач или контентных надстройках можно использовать свойство document объекта Context для получения доступа к свойствам и методам объекта Document, чтобы взаимодействовать с содержимым документов Word, электронными таблицами Excel или расписаниями Project. Аналогично этому в надстройках Outlook можно использовать свойство mailbox объекта Context для получения доступа к свойствам и методам объекта Mailbox, чтобы взаимодействовать с контентом сообщений, запросов на собрание или встреч.

Объект Context также предоставляет доступ к свойствам contentLanguage и displayLanguage , позволяющим определить языковой стандарт (язык), используемый в документе или элементе или в приложении Office. Свойство roamingSettings позволяет получить доступ к элементам объекта RoamingSettings, в котором хранятся настройки, специфичные для надстроек почтовых ящиков отдельных пользователей. Наконец, объект Context предоставляет свойство ui, позволяющее надстройке открывать всплывающие диалоговые окна.

Объект Document

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

Чтобы взаимодействовать с данными документа в Excel, PowerPoint и Word, интерфейс API предоставляет объект Document. Члены объекта позволяют Document получать доступ к данным следующими способами.

• Читать и записывать активные выделенные элементы в виде текста, смежных ячеек (матриц) или таблиц.

• Табличные данные (матрицы или таблицы).

• Привязки (создаются с помощью методов Bindings "add" объекта).

• Настраиваемые части XML (только для Word).

• Параметры или состояние надстройки, сохраняемые в документе отдельными надстройками.

Вы также можете использовать объект Document для взаимодействия с данными в документах Project. Функциональность API, специфичная для проекта, задокументирована в членах абстрактного класса ProjectDocument . Узнайте больше о создании надстроек области задач для Project в статье, посвященной надстройкам области задач для Project.

Все эти формы доступа к данным начинаются с экземпляра абстрактного Document объекта.

Вы можете получить доступ к экземпляру Document объекта при инициализации области задач или надстройки контента с помощью свойства Contextдокумента объекта. Объект Document определяет общие способы доступа к данным, совместно используемые в документах Word и Excel, а также предоставляет доступ к объекту CustomXmlParts для документов Word.

Объект Document поддерживает четыре способа доступа разработчиков к содержимому документа.

• Доступ на основе выделенных фрагментов.

• Доступ на основе привязок.

• Доступ на основе настраиваемых XML-частей (только для Word).

• Доступ на основе целого документа (только для PowerPoint и Word).

Чтобы помочь вам понять, как работают методы доступа к данным на основе выбора и привязки, в этой статье сначала объясняется, как API доступа к данным обеспечивают согласованный доступ к данным в различных приложениях Office.

Единообразный доступ к данным в приложениях Office

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

Для создания расширений, которые органично работают с различными документами Office, API Office JavaScript абстрагирует особенности каждого приложения Office с помощью общих типов данных и возможности объединения различного содержимого документа в три распространенных типа данных.

Общие типы данных

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

Тип данных	Описание	Поддержка ведущего приложения
Текст	Предоставляет строковое представление данных в выделенном фрагменте или привязке.	В Excel, Project и PowerPoint поддерживается только простой текст. В Word поддерживаются три формата текста: простой текст, HTML и Office Open XML (OOXML). При выборе текста в ячейке в Excel методы выделения осуществляют чтение и запись всего содержимого ячейки, даже если в ячейке выделена только часть текста. При выделении текста в Word и PowerPoint методы выделения осуществляют чтение и запись только для выполнения выбранных символов. Project и PowerPoint поддерживают доступ к данным только на основе выделения.
Matrix	Предоставляет данные в выборе или привязке как двумерный объект Array, который в JavaScript реализован как массив массивов. Например, две строки значений string в двух столбцах будут выглядеть как [['a', 'b'], ['c', 'd']], а один столбец, состоящий из трех строк, — как [['a'], ['b'], ['c']].	Доступ к матричным данным поддерживается только в Excel и Word.
Таблица	Предоставляет данные в выделенном фрагменте или привязке в виде объекта TableData. Объект TableData предоставляет данные через headers свойства and rows .	Доступ к табличным данным поддерживается только в Excel и Word.

Приведение типов данных

Методы доступа к данным объектов и DocumentBinding поддерживают указание нужного типа данных с помощью параметра CoercionType этих методов и соответствующих значений перечисления CoercionType . Вне зависимости от действительной формы привязки различные приложения Office поддерживают общие типы данных, пытаясь привести данные в запрошенный тип данных. Например, если выделена таблица Word или абзац, разработчик может указать чтение этой таблицы в виде неформатированного текста, HTML, Office Open XML или таблицы, а API производит необходимые преобразования данных.

Совет

В каких случаях следует использовать для доступа к данным матрицы, а в каких — coercionType? Если необходимо, чтобы табличные данные динамически увеличивались при добавлении строк и столбцов, и необходимо работать с заголовками таблиц, следует использовать тип данных таблицы (указав параметр CoercionType метода доступа к данным объекта DocumentBinding или "table"Office.CoercionType.Tableили ). Добавление строк и столбцов в структуре данных поддерживается как табличными, так и матричными данными, но присоединение строк и столбцов поддерживается только табличными данными. Если вы не планируете добавлять строки и столбцы, а данные не требуют функциональности заголовка, следует использовать матричный тип данных (указав параметр coercionType метода доступа к данным как "matrix" или Office.CoercionType.Matrix), который обеспечивает более простую модель взаимодействия с данными.

Если данные не могут быть приведены к указанному типу, свойство AsyncResult.status в обратном вызове возвращает "failed". Используйте свойство AsyncResult.error для доступа к объекту Error со сведениями о причинах сбоя вызова метода.

Работа с выделенными фрагментами с помощью объекта Document

Объект Document имеет методы, которые можно использовать для чтения и записи в текущий выбранный пользователем формат "get and set". Для этого Document объект предоставляет методы and getSelectedDataAsyncsetSelectedDataAsync .

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

Работа с привязками с помощью объектов "Привязки" и "Привязки"

Доступ к данным на основе привязок позволяет надстройкам области задач и контентным надстройкам получать единообразный доступ к определенной области документа или электронной таблицы через идентификатор, связанный с привязкой. Сначала надстройка должна создать привязку с помощью вызова одного из методов, связывающих часть документа с уникальным идентификатором: addFromPromptAsync, addFromSelectionAsync или addFromNamedItemAsync. После настройки привязки надстройка может использовать предоставленный идентификатор для доступа к данным, содержащимся в связанном регионе документа или электронной таблицы. Создание привязок обеспечивает надстройке следующее значение:

• Предоставляет доступ к общим структурам данных в поддерживаемых приложениях Office, таким как таблицы, диапазоны или текст (непрерывный набор символов).

• Позволяет производить операции чтения или записи без необходимости выделения пользователем фрагмента.

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

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

Объект Bindings предоставляет метод getAllAsync, который обеспечивает доступ к набору всех привязок, установленных в этом документе или листе. Доступ к отдельной привязке по ее идентификатору можно получить с помощью метода Bindings.getBindingByIdAsync или функции Office.select . Установите новые привязки и удалите существующие с помощью одного из следующих методов Bindings объекта: addFromSelectionAsync, addFromPromptAsync, addFromNamedItemAsync или releaseByIdAsync.

При создании привязки с помощью addFromSelectionAsyncметодов , addFromPromptAsyncили addFromNamedItemAsync вы указываете тип привязки с помощью параметра bindingType .

Тип привязки	Описание	Поддержка ведущего приложения
Привязка текста	Выполняет привязку к области документа, которая может быть представлена как текст.	В Word допустимо большинство смежных выделенных элементов, в то время как в Excel привязкой к тексту может быть выделение только одной ячейки. В Excel поддерживается только обычный текст. В Word поддерживаются три формата: обычный текст, HTML и Open XML для Office.
Привязка матрицы	Выполняет привязку к фиксированной области документа, содержащей табличные данные без заголовков. Данные в привязке матрицы записываются или считываются как двумерный Array, который в JavaScript реализован как массив массивов. Например, две строки значений string в двух столбцах можно записать или прочитать как [['a', 'b'], ['c', 'd']], а один столбец, состоящий из трех строк, — как [['a'], ['b'], ['c']].	В Excel для установки матричной привязки может использоваться любое связанное выделение ячеек. В Word матричная привязка поддерживается только таблицами.
Привязка таблицы	Выполняет привязку к области документа, содержащей таблицу с заголовками. Данные в привязке таблицы записываются или считываются как объект TableData. Объект TableData предоставляет данные через свойства заголовков и строк.	Любая таблица Excel или Word может быть основой для табличной привязки. После создания табличной привязки каждая новая строка или столбец, добавляемые пользователем в таблицу, автоматически включаются в привязку.

После создания привязки с помощью одного из трех методов Bindings "add" объекта можно работать с данными и свойствами привязки, используя методы соответствующего объекта: MatrixBinding, TableBinding или TextBinding. Все три объекта наследуют методы getDataAsync и setDataAsync объекта Binding, позволяющие работать со связанными данными.

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

Работа с пользовательскими частями XML с помощью объектов CustomXmlParts и CustomXmlPart

Область применения: надстройки области задач Word

Объекты CustomXmlParts и CustomXmlPart интерфейса API предоставляют доступ к настраиваемым частям XML в документах Word, которые позволяют работать с содержимым документа на основе XML. Дополнительные сведения см. в статье Пользовательские данные XML в Excel и Word.

Работа со всем документом с помощью метода getFileAsync

Область применения: надстройки области задач Word и PowerPoint

Метод Document.getFileAsync и члены объектов File и Slice обеспечивают возможность получения целых файлов документов Word и PowerPoint срезами (блоками) размером до 4 МБ за раз. Дополнительные сведения см. в статье Получение документа целиком из надстройки для PowerPoint или Word.

Объект Mailbox

Область применения: надстройки Outlook

Надстройки Outlook, в основном, используют набор API, предоставляемый через объект Mailbox. Чтобы получить доступ к объектам и элементам для использования в надстройках Outlook, таким как объект Item в режиме создания или чтения, используйте свойство mailbox объекта Context для доступа к объекту Mailbox. Ниже приведен код в качестве примера.

// Access the Item object.
const item = Office.context.mailbox.item;

Важно!

Обратите внимание, что при вызове Office.context.mailbox.item сообщения следует помнить, что область чтения в клиенте Outlook должна быть включена. Рекомендации по настройке области чтения см. в статье "Использование и настройка области чтения для предварительного просмотра сообщений".

Кроме того, надстройки Outlook могут использовать перечисленные ниже объекты.

• Объект Office для инициализации.

• Объект Context для получения доступа к контенту и отображения языковых свойств.

Сведения об использовании JavaScript в надстройках Outlook см. в статье "Надстройки Outlook". Сведения об API JavaScript для Outlook см. на странице справочника по API Outlook .