Общая объектная модель API JavaScript
Важно!
Эта статья относится к общим API, модели API JavaScript для Office, которая была представлена в Office 2013. Эти API-интерфейсы включают такие компоненты, как пользовательский интерфейс, диалоговые окна и параметры клиентов, общие для нескольких типов приложений Office. Надстройки Outlook используют только общие API, в частности подмножество API, предоставленных в объекте Mailbox.
Вы должны использовать общие API только в сценариях, которые не поддерживаются API-интерфейсами для определенных приложений. Сведения о том, как использовать общие API вместо API для определенных приложений, см. в статье Общие сведения об API JavaScript для Office.
API JavaScript для Office предоставляют доступ к базовым функциям клиентского приложения Office. В основном такой доступ осуществляется при помощи нескольких значимых объектов. Объект Context предоставляет доступ к среде выполнения после инициализации. Объект Document предоставляет пользователю управление документом Excel, PowerPoint или Word. Объект Mailbox предоставляет надстройке Outlook доступ к сообщениям, встречам и профилям пользователей. Понимание связей между этими высокоуровневые объекты является основой надстройки Office.
Объект Context
Область применения: все типы надстроек
Когда надстройка инициализирована, она содержит множество различных объектов, с которыми она может взаимодействовать в среде выполнения. Контекст среды выполнения надстройки представлен в API объектом Context. Объект Context — это основной объект, предоставляющий доступ к наиболее важным объектам 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 для доступа к данным следующими способами.
Читать и записывать активные выделенные элементы в виде текста, смежных ячеек (матриц) или таблиц.
Табличные данные (матрицы или таблицы).
Привязки (создаются с помощью методов
Bindingsadd объекта).Настраиваемые части XML (только для Word).
Параметры или состояние надстройки, сохраняемые в документе отдельными надстройками.
Объект также можно использовать для взаимодействия с данными Document в документах Project. Возможности API, относящиеся к Project, документированы в абстрактном классе ProjectDocument. Узнайте больше о создании надстроек области задач для Project в статье, посвященной надстройкам области задач для Project.
Все эти формы доступа к данным начинаются с экземпляра абстрактного Document объекта.
Получить доступ к экземпляру Document объекта можно при инициализации области задач или контентной надстройки с помощью свойства Contextdocument объекта . Объект Document определяет общие методы доступа к данным в документах Word и Excel, а также предоставляет доступ к объекту CustomXmlParts для Word документов.
Объект Document поддерживает четыре способа доступа разработчиков к содержимому документа.
Доступ на основе выделенных фрагментов.
Доступ на основе привязок.
Доступ на основе настраиваемых XML-частей (только для Word).
Доступ на основе целого документа (только для PowerPoint и Word).
Для лучшего понимания работы способов доступа к данным на основе выделенных фрагментов и привязок мы сначала объясним, как API доступа к данным обеспечивают единообразный доступ к данным в различных приложениях Office.
Единообразный доступ к данным в приложениях Office
Область применения: надстройки области задач и контентные надстройки
Чтобы создать расширения, которые легко работают в разных документах Office, API JavaScript для Office абстрагирует особенности каждого приложения Office с помощью общих типов данных и возможности принудительного применения разных типов документов к трем общим типам данных.
Общие типы данных
Во время доступа к данным как через выделенные фрагменты, так и через привязки контент документа предоставляется через типы данных, которые являются общими во всех поддерживаемых приложениях Office. Поддерживаются три main типа данных.
| Тип данных | Описание | Поддержка ведущего приложения |
|---|---|---|
| Текст | Предоставляет строковое представление данных в выделенном фрагменте или привязке. | В 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 свойства и rows . |
Доступ к данным таблиц поддерживается только в Excel и Word. |
Приведение типов данных
Методы доступа к данным объектов Document и Binding поддерживают указание требуемого типа данных с помощью параметра coercionType этих методов и соответствующих значений перечисления CoercionType . Вне зависимости от действительной формы привязки различные приложения Office поддерживают общие типы данных, пытаясь привести данные в запрошенный тип данных. Например, если выделена таблица Word или абзац, разработчик может указать чтение этой таблицы в виде неформатированного текста, HTML, Office Open XML или таблицы, а API производит необходимые преобразования данных.
Совет
В каких случаях следует использовать для доступа к данным матрицы, а в каких — coercionType? Если табличные данные должны динамически увеличиваться при добавлении строк и столбцов и работать с заголовками таблиц, следует использовать тип данных таблицы (указав параметр DocumentcoercionType метода доступа к данным объекта или Binding как "table" или Office.CoercionType.Table). Добавление строк и столбцов в структуре данных поддерживается как табличными, так и матричными данными, но присоединение строк и столбцов поддерживается только табличными данными. Если вы не планируете добавлять строки и столбцы, а для данных не требуется функциональность заголовка, следует использовать тип данных матрицы (указав параметр coercionType метода доступа к данным как "matrix" или Office.CoercionType.Matrix), который предоставляет более простую модель взаимодействия с данными.
Если данные невозможно привести к заданному типу, то свойство AsyncResult.status в функции обратного вызова возвращает значение "failed", и можно использовать свойство AsyncResult.error, чтобы получить доступ к объекту Error со сведениями о причине ошибки во время вызова метода.
Работа с выделенными фрагментами с помощью объекта Document
Объект Document предоставляет методы, позволяющие считывать и записывать текущий выбор пользователя в режиме "получить и задать". Для этого Document объект предоставляет методы getSelectedDataAsync и setSelectedDataAsync .
Примеры кода, демонстрирующие выполнение задач с выделенными фрагментами, см. в статье Чтение и запись данных при активном выделении фрагмента в документе или электронной таблице.
Работа с привязками с помощью объектов Bindings и Binding
Доступ к данным на основе привязок позволяет надстройкам области задач и контентным надстройкам получать единообразный доступ к определенной области документа или электронной таблицы через идентификатор, связанный с привязкой. Сначала надстройка должна создать привязку с помощью вызова одного из методов, связывающих часть документа с уникальным идентификатором: addFromPromptAsync, addFromSelectionAsync или addFromNamedItemAsync. После настройки привязки надстройка может использовать предоставленный идентификатор для доступа к данным, содержащимся в связанном регионе документа или электронной таблицы. Создание привязок предоставляет надстройке следующее значение.
Разрешает доступ к общим структурам данных в поддерживаемых приложениях Office, таким как: таблицы, диапазоны или текст (связанная последовательность знаков).
Позволяет производить операции чтения или записи без необходимости выделения пользователем фрагмента.
Устанавливает отношение между надстройкой и данными в документе. Привязки сохраняются в документе и могут использоваться позже.
Установка привязки также позволяет подписываться на данные и выбирать изменения событий, относящиеся к конкретной области документа или электронной таблицы. Это означает, что надстройка уведомляется только об изменениях, происходящих внутри данной конкретной области, в отличие от изменений, затрагивающих в целом весь документ или электронную таблицу.
Объект Bindings предоставляет метод getAllAsync, который обеспечивает доступ к набору всех привязок, установленных в этом документе или листе. Доступ к отдельной привязке можно получить по ее идентификатору с помощью метода Bindings.getBindingByIdAsync или функции Office.select . Можно установить новые и удалить существующие привязки с помощью одного из следующих методов Bindings объекта: addFromSelectionAsync, addFromPromptAsync, addFromNamedItemAsync или releaseByIdAsync.
Существует три разных типа привязок, которые указываются с помощью параметра bindingType при создании привязки addFromSelectionAsyncс помощью методов или addFromNamedItemAsyncaddFromPromptAsync .
| Тип привязки | Описание | Поддержка ведущего приложения |
|---|---|---|
| Привязка текста | Выполняет привязку к области документа, которая может быть представлена как текст. | В 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. Все три этих объекта наследуют методы BindinggetDataAsync и setDataAsync объекта, которые позволяют взаимодействовать с привязанными данными.
Примеры кода, демонстрирующие выполнение задач с привязками, см. в статье Привязка к областям в документе или электронной таблице.
Работа с пользовательскими XML-частями с помощью объектов CustomXmlParts и CustomXmlPart
Область применения: надстройки области задач Word
Объекты CustomXmlParts и CustomXmlPart интерфейса API предоставляют доступ к настраиваемым частям XML в документах Word, которые позволяют работать с содержимым документа на основе XML. Демонстрации работы с объектами CustomXmlParts и CustomXmlPart см. в примере кода Word-add-in-Work-with-custom-XML-parts.
Работа со всем документом с помощью метода 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 .
Office Add-ins