Общая объектная модель 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 для доступа к данным следующими способами.

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

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

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

  • Настраиваемые части 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.
Table Предоставляет данные в выделенном фрагменте или привязке в виде объекта 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;

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

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

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

  • Объект RoamingSettings для сохранения пользовательских свойств, относящихся к надстройке Outlook, в почтовом ящике пользователя, в котором установлено приложение.

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