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

Важно!

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

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

Office API JavaScript дают доступ к Office клиентского приложения. В основном такой доступ осуществляется при помощи нескольких значимых объектов. Объект Context предоставляет доступ к среде выполнения после инициализации. Объект Document предоставляет пользователю управление документом Excel, PowerPoint или Word. Объект почтовых ящиков предоставляет 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 объекта).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Совет

В каких случаях следует использовать для доступа к данным матрицы, а в каких — coercionType? Если при добавлении строк и столбцов необходимо динамическое развитие табулярных данных, и вам необходимо работать с загонами таблицы, следует использовать тип данных таблицы (указав параметр coercionType метода доступа к объектным данным как или Document 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 методами или addFromPromptAsync addFromNamedItemAsync методами.

Тип привязки Описание Поддержка ведущего приложения
Привязка текста Выполняет привязку к области документа, которая может быть представлена как текст. В 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 объекта: MatrixBinding, TableBindingили TextBinding. Все три этих объекта наследуют методы getDataAsync и setDataAsync объекта, которые позволяют взаимодействовать с Binding связанными данными.

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

Работа с пользовательскими частями 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.
var item = Office.context.mailbox.item;

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

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

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

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

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