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

Надстройки JavaScript для Office предоставляют доступ к базовым функциям ведущего приложения.Office JavaScript add-ins give access to the host’s underlying functionality. В основном такой доступ осуществляется при помощи нескольких значимых объектов.Most of this access goes through a few important objects. Объект Context предоставляет доступ к среде выполнения после инициализации.The Context object gives access to the runtime environment after initialization. Объект Document предоставляет пользователю управление документом Excel, PowerPoint или Word.The Document object gives the user control over an Excel, PowerPoint, or Word document. Объект Mailbox предоставляет надстройкам Outlook доступ к сообщениям и профилям пользователей.The Mailbox object gives an Outlook add-in access to messages and user profiles. Связи между этими объектами высокого уровня — это основа надстроек JavaScript.Understanding the relationships between these high-level objects is the foundation of a JavaScript add-in.

Объект ContextContext object

Область применения: все типы надстроекApplies to: All add-in types

Когда надстройка инициализирована, она содержит множество различных объектов, с которыми она может взаимодействовать в среде выполнения.When an add-in is initialized, it has many different objects that it can interact with in the runtime environment. Контекст среды выполнения надстройки представлен в API объектом Context.The add-in's runtime context is reflected in the API by the Context object. Объект Context — это основной объект, предоставляющий доступ к наиболее важным объектам API, таким как Document и Mailbox, которые в свою очередь предоставляют доступ к документу и содержимому почтового ящика.The Context is the main object that provides access to the most important objects of the API, such as the Document and Mailbox objects, which in turn provide access to document and mailbox content.

Например, в надстройках области задач или контентных надстройках можно использовать свойство document объекта Context для получения доступа к свойствам и методам объекта Document, чтобы взаимодействовать с содержимым документов Word, электронными таблицами Excel или расписаниями Project. Аналогично этому в надстройках Outlook можно использовать свойство mailbox объекта Context для получения доступа к свойствам и методам объекта Mailbox, чтобы взаимодействовать с контентом сообщений, запросов на собрание или встреч.For example, in task pane or content add-ins, you can use the document property of the Context object to access the properties and methods of the Document object to interact with the content of Word documents, Excel worksheets, or Project schedules. Similarly, in Outlook add-ins, you can use the mailbox property of the Context object to access the properties and methods of the Mailbox object to interact with the message, meeting request, or appointment content.

Объект Context также предоставляет доступ к свойствам contentLanguage и displayLanguage, которые позволяют задать языковые параметры, используемые в документе, элементе или ведущем приложении.The Context object also provides access to the contentLanguage and displayLanguage properties that let you determine the locale (language) used in the document or item, or by the host application. Свойство roamingSettings позволяет получить доступ к элементам объекта RoamingSettings, в котором хранятся настройки, специфичные для надстроек почтовых ящиков отдельных пользователей.The roamingSettings property lets you access the members of the RoamingSettings object, which stores settings specific to your add-in for individual users' mailboxes. Наконец, объект Context предоставляет свойство ui, позволяющее надстройке открывать всплывающие диалоговые окна.Finally, the Context object provides a ui property that enables your add-in to launch pop-up dialogs.

Объект DocumentDocument object

Область применения: надстройки области задач и контентные надстройкиApplies to: Content and task pane add-in types

Чтобы взаимодействовать с данными документа в Excel, PowerPoint и Word, интерфейс API предоставляет объект Document. Члены объекта Document можно использовать для получения доступа к данным в следующем виде:To interact with document data in Excel, PowerPoint, and Word, the API provides the Document object. You can use Document object members to access data from the following ways:

  • Читать и записывать активные выделенные элементы в виде текста, смежных ячеек (матриц) или таблиц.Read and write to active selections in the form of text, contiguous cells (matrices), or tables.

  • Табличные данные (матрицы или таблицы).Tabular data (matrices or tables).

  • Привязки (созданные методами add объекта Bindings).Bindings (created with the "add" methods of the Bindings object).

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

  • Параметры или состояние надстройки, сохраняемые в документе отдельными надстройками.Settings or add-in state persisted per add-in on the document.

Кроме того, объект Document можно использовать для взаимодействия с данными в документах Project. Возможности API, относящиеся к Project, документированы в абстрактном классе ProjectDocument. Узнайте больше о создании надстроек области задач для Project в статье, посвященной надстройкам области задач для Project.You can also use the Document object to interact with data in Project documents. The Project-specific functionality of the API is documented in the members ProjectDocument abstract class. For more information about creating task pane add-ins for Project, see Task pane add-ins for Project.

Все эти виды доступа к данным начинаются с экземпляра абстрактного объекта Document.All these forms of data access start from an instance of the abstract Document object.

Получить доступ к экземпляру объекта Document после инициализации надстройки области задач или контентной надстройки можно с помощью свойства document объекта Context. Объект Document определяет общие функции доступа к данным, используемые в документах Word и Excel, а также предоставляет доступ к объекту CustomXmlParts для документов Word.You can access an instance of the Document object when the task pane or content add-in is initialized by using the document property of the Context object. The Document object defines common data access functions shared across Word and Excel documents, and also provides access to the CustomXmlParts object for Word documents.

Объект Document поддерживает четыре способа, которые разработчики могут применить для доступа к контенту документов:The Document object supports four ways for developers to access document contents:

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

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

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

  • Доступ на основе целого документа (только для PowerPoint и Word).Entire document-based access (PowerPoint and Word only)

Для лучшего понимания работы способов доступа к данным на основе выделенных фрагментов и привязок мы сначала объясним, как API доступа к данным обеспечивают единообразный доступ к данным в различных приложениях Office.To help you understand how selection- and binding-based data access methods work, we will first explain how the data-access APIs provide consistent data access across different Office applications.

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

Область применения: надстройки области задач и контентные надстройкиApplies to: Content and task pane add-in types

Чтобы создать расширения, которые прозрачно работают в различных документах Office, абстрактные классы API JavaScript для Office исключают особенности конкретных приложений Office с помощью общих типов данных и возможности приводить содержимое разных документов к трем общим типам данных.To create extensions that seamlessly work across different Office documents, the JavaScript API for Office abstracts away the particularities of each Office application through common data types and the ability to coerce different document contents into three common data types.

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

Во время доступа к данным как через выделенные фрагменты, так и через привязки контент документа предоставляется через типы данных, которые являются общими во всех поддерживаемых приложениях Office. В Office 2013 поддерживается три основных типа данных:In both selection-based and binding-based data access, document contents are exposed through data types that are common across all the supported Office applications. In Office 2013, three main data types are supported:

Тип данныхData type ОписаниеDescription Поддержка ведущего приложенияHost application support
ТекстText Предоставляет строковое представление данных в выделенном фрагменте или привязке.Provides a string representation of the data in the selection or binding. В Excel 2013, Project 2013 и PowerPoint 2013 поддерживается только обычный текст. В Word 2013 поддерживаются три текстовых формата: обычный текст, HTML и Office Open XML (OOXML). При выборе текста в ячейке в Excel методы выделения осуществляют чтение и запись всего содержимого ячейки, даже если в ячейке выделена только часть текста. При выделении текста в Word и PowerPoint методы выделения осуществляют чтение и запись только для выполнения выбранных символов. Project 2013 и PowerPoint 2013 поддерживает только доступ к данным на основе выделения.In Excel 2013, Project 2013, and PowerPoint 2013, only plain text is supported. In Word 2013, three text formats are supported: plain text, HTML, and Office Open XML (OOXML). When text is selected in a cell in Excel, selection-based methods read and write to the entire contents of the cell, even if only a portion of the text is selected in the cell. When text is selected in Word and PowerPoint, selection-based methods read and write only to the run of characters that are selected. Project 2013 and PowerPoint 2013 support only selection-based data access.
МатрицаMatrix Предоставляет данные в выборе или привязке как двумерный объект Array, который в JavaScript реализован как массив массивов. Например, две строки значений string в двух столбцах будут выглядеть как [['a', 'b'], ['c', 'd']], а один столбец, состоящий из трех строк, — как [['a'], ['b'], ['c']].Provides the data in the selection or binding as a two dimensional Array, which in JavaScript is implemented as an array of arrays. For example, two rows of string values in two columns would be [['a', 'b'], ['c', 'd']], and a single column of three rows would be [['a'], ['b'], ['c']]. Доступ к матричным данным поддерживается только в Excel 2013 и Word 2013.Matrix data access is supported only in Excel 2013 and Word 2013.
ТаблицаTable Предоставляет данные в выделенном фрагменте или привязке в виде объекта TableData. Объект TableData предоставляет данные через свойства headers и rows.Provides the data in the selection or binding as a TableData object. The TableData object exposes the data through the headers and rows properties. Доступ к данным таблицы поддерживается только в Excel 2013 и Word 2013.Table data access is supported only in Excel 2013 and Word 2013.

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

Методы доступа к данным объектам Document и Binding поддерживают указание желаемого типа данных, используя параметр coercionType этих методов и соответствующие значения перечисления CoercionType. Вне зависимости от действительной формы привязки различные приложения Office поддерживают общие типы данных, пытаясь привести данные к запрашиваемому типу данных. Например, если выделена таблица Word или абзац, разработчик может считывать эту таблицу в виде неформатированного текста, HTML, Office Open XML или таблицы, а API производит необходимые преобразования данных.The data access methods on the Document and Binding objects support specifying the desired data type using the coercionType parameter of these methods, and corresponding CoercionType enumeration values. Regardless of the actual shape of the binding, the different Office applications support the common data types by trying to coerce the data into the requested data type. For example, if a Word table or paragraph is selected, the developer can specify to read it as plain text, HTML, Office Open XML, or a table, and the API implementation handles the necessary transformations and data conversions.

Совет

В каких случаях следует использовать для доступа к данным матрицы, а в каких — coercionType? Если вы хотите, чтобы табличные данные динамически росли при добавлении строк и столбцов, и вам нужно работать с заголовками таблиц, используйте табличный тип данных (для этого укажите параметр coercionType метода для доступа к данным объекта Document либо Binding в виде "table" или Office.CoercionType.Table). Добавление строк и столбцов в структуру данных поддерживается как для табличных, так и для матричных данных, но добавление строк и столбцов в конец поддерживается только для табличных данных. Если вы не планируете добавлять строки и столбцы, а для данных не требуются заголовки, следует использовать матричный тип данных (указав параметр coercionType метода доступа к данным в виде "matrix" или Office.CoercionType.Matrix), что позволяет использовать упрощенный способ взаимодействия с данными.When should you use the matrix versus table coercionType for data access? If you need your tabular data to grow dynamically when rows and columns are added, and you must work with table headers, you should use the table data type (by specifying the coercionType parameter of a Document or Binding object data access method as "table" or Office.CoercionType.Table). Adding rows and columns within the data structure is supported in both table and matrix data, but appending rows and columns is supported only for table data. If you aren't planning on adding rows and columns, and your data doesn't require header functionality, then you should use the matrix data type (by specifying the coercionType parameter of the data access method as "matrix" or Office.CoercionType.Matrix), which provides a simpler model of interacting with the data.

Если данные невозможно привести к заданному типу, то свойство AsyncResult.status в функции обратного вызова возвращает значение "failed", и можно использовать свойство AsyncResult.error, чтобы получить доступ к объекту Error со сведениями о причине ошибки во время вызова метода.If the data can't be coerced to the specified type, the AsyncResult.status property in the callback returns "failed", and you can use the AsyncResult.error property to access an Error object with information about why the method call failed.

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

Объект Document предоставляет методы, позволяющие выполнять чтение и запись к текущему выделенному фрагменту пользователя в виде "get and set". Для этого объект Document предоставляет методы getSelectedDataAsync и setSelectedDataAsync.The Document object exposes methods that let you to read and write to the user's current selection in a "get and set" fashion. To do that, the Document object provides the getSelectedDataAsync and setSelectedDataAsync methods.

Примеры кода, демонстрирующие выполнение задач с выделенными фрагментами, см. в статье Чтение и запись данных при активном выделении фрагмента в документе или электронной таблице.For code examples that demonstrate how to perform tasks with selections, see Read and write data to the active selection in a document or spreadsheet.

Работа с привязками с помощью объектов Bindings и BindingWorking with bindings using the Bindings and Binding objects

Доступ к данным на основе привязок позволяет надстройкам области задач и контентным надстройкам получать единообразный доступ к определенной области документа или электронной таблицы через идентификатор, связанный с привязкой. Сначала надстройка должна создать привязку с помощью вызова одного из методов, связывающих часть документа с уникальным идентификатором: addFromPromptAsync, addFromSelectionAsync или addFromNamedItemAsync. После настройки привязки надстройка может использовать предоставленный идентификатор для доступа к данным, содержащимся в связанном регионе документа или электронной таблицы. Создание привязок предоставляет указанные ниже возможности.Binding-based data access enables content and task pane add-ins to consistently access a particular region of a document or spreadsheet through an identifier associated with a binding. The add-in first needs to establish the binding by calling one of the methods that associates a portion of the document with a unique identifier: addFromPromptAsync, addFromSelectionAsync, or addFromNamedItemAsync. After the binding is established, the add-in can use the provided identifier to access the data contained in the associated region of the document or spreadsheet. Creating bindings provides the following value to your add-in:

  • Разрешает доступ к общим структурам данных в поддерживаемых приложениях Office, таким как: таблицы, диапазоны или текст (связанная последовательность знаков).Permits access to common data structures across supported Office applications, such as: tables, ranges, or text (a contiguous run of characters).

  • Позволяет производить операции чтения или записи без необходимости выделения пользователем фрагмента.Enables read/write operations without requiring the user to make a selection.

  • Устанавливает отношение между надстройкой и данными в документе. Привязки сохраняются в документе и могут использоваться позже.Establishes a relationship between the add-in and the data in the document. Bindings are persisted in the document, and can be accessed at a later time.

Установка привязки также позволяет подписываться на данные и выбирать изменения событий, относящиеся к конкретной области документа или электронной таблицы. Это означает, что надстройка уведомляется только об изменениях, происходящих внутри данной конкретной области, в отличие от изменений, затрагивающих в целом весь документ или электронную таблицу.Establishing a binding also allows you to subscribe to data and selection change events that are scoped to that particular region of the document or spreadsheet. This means that the add-in is only notified of changes that happen within the bound region as opposed to general changes across the whole document or spreadsheet.

Объект Bindings предоставляет метод getAllAsync, который обеспечивает доступ к набору всех привязок, установленных в этом документе или листе. Доступ к отдельной привязке можно получить по ее идентификатору с помощью методов Bindings.getBindingByIdAsync или Office.select. Можно создать новые привязки, а также удалить существующие, используя один из перечисленных ниже методов объекта Bindings: addFromSelectionAsync, addFromPromptAsync, addFromNamedItemAsync или releaseByIdAsync.The Bindings object exposes a getAllAsync method that gives access to the set of all bindings established on the document or spreadsheet. An individual binding can be accessed by its ID using either the Bindings.getBindingByIdAsync or Office.select methods. You can establish new bindings as well as remove existing ones by using one of the following methods of the Bindings object: addFromSelectionAsync, addFromPromptAsync, addFromNamedItemAsync, or releaseByIdAsync.

Имеется три различных вида привязки, которые определяются с помощью параметра bindingType при создании привязки с помощью методов addFromSelectionAsync, addFromPromptAsync или addFromNamedItemAsync:There are three different types of bindings that you specify with the bindingType parameter when you create a binding with the addFromSelectionAsync, addFromPromptAsync or addFromNamedItemAsync methods:

Тип привязкиBinding type ОписаниеDescription Поддержка ведущего приложенияHost application support
Привязка текстаText binding Выполняет привязку к области документа, которая может быть представлена как текст.Binds to a region of the document that can be represented as text. В Word поддерживается большинство связанных выделений, тогда как в Excel для привязки текста можно использовать только выделения отдельных ячеек. Excel поддерживает только обычный текст, а Word — три формата: обычный текст, HTML и Open XML для Office.In Word, most contiguous selections are valid, while in Excel only single cell selections can be the target of a text binding. In Excel, only plain text is supported. In Word, three formats are supported: plain text, HTML, and Open XML for Office.
Привязка матрицыMatrix binding Выполняет привязку к фиксированной области документа, содержащей табличные данные без заголовков. Данные в привязке матрицы записываются или считываются как двумерный Array, который в JavaScript реализован как массив массивов. Например, две строки значений string в двух столбцах можно записать или прочитать как [['a', 'b'], ['c', 'd']], а один столбец, состоящий из трех строк, — как [['a'], ['b'], ['c']].Binds to a fixed region of a document that contains tabular data without headers. Data in a matrix binding is written or read as a two dimensional Array, which in JavaScript is implemented as an array of arrays. For example, two rows of string values in two columns can be written or read as [['a', 'b'], ['c', 'd']], and a single column of three rows can be written or read as [['a'], ['b'], ['c']]. В Excel для установки матричной привязки может использоваться любое связанное выделение ячеек. В Word матричная привязка поддерживается только таблицами.In Excel, any contiguous selection of cells can be used to establish a matrix binding. In Word, only tables support matrix binding.
Привязка таблицыTable binding Выполняет привязку к области документа, содержащей таблицу с заголовками. Данные в привязке таблицы записываются или считываются как объект TableData. Объект TableData предоставляет данные с помощью свойств headers и rows.Binds to a region of a document that contains a table with headers. Data in a table binding is written or read as a TableData object. The TableData object exposes the data through the headers and rows properties. Любая таблица Excel или Word может быть основой для табличной привязки. После создания табличной привязки каждая новая строка или столбец, добавляемые пользователем в таблицу, автоматически включаются в привязку.Any Excel or Word table can be the basis for a table binding. After you establish a table binding, each new row or column a user adds to the table is automatically included in the binding.

После создания привязки с помощью одного из трех методов add объекта Bindings можно работать с данными и свойствами привязки с помощью методов соответствующего объекта: MatrixBinding, TableBinding или TextBinding. Все три эти объекта наследуют методы getDataAsync и setDataAsync объекта Binding, позволяющие взаимодействовать с привязанными данными.After a binding is created by using one of the three "add" methods of the Bindings object, you can work with the binding's data and properties by using the methods of the corresponding object: MatrixBinding, TableBinding, or TextBinding. All three of these objects inherit the getDataAsync and setDataAsync methods of the Binding object that enable to you interact with the bound data.

Примеры кода, демонстрирующие выполнение задач с привязками, см. в статье Привязка к областям в документе или электронной таблице.For code examples that demonstrate how to perform tasks with bindings, see Bind to regions in a document or spreadsheet.

Работа с настраиваемыми частями XML с помощью объектов CustomXmlParts и CustomXmlPartWorking with custom XML parts using the CustomXmlParts and CustomXmlPart objects

Область применения: надстройки области задач WordApplies to: Task pane add-ins for Word

Объекты CustomXmlParts и CustomXmlPart интерфейса API предоставляют доступ к настраиваемым частям XML в документах Word, которые позволяют работать с содержимым документа на основе XML.The CustomXmlParts and CustomXmlPart objects of the API provide access to custom XML parts in Word documents, which enable XML-driven manipulation of the contents of the document. Примеры работы с объектами CustomXmlParts и CustomXmlPart см. в примере кода Word-add-in-Work-with-custom-XML-parts.For demonstrations of working with the CustomXmlParts and CustomXmlPart objects, see the Word-add-in-Work-with-custom-XML-parts code sample.

Работа с целым документом с помощью метода getFileAsyncWorking with the entire document using the getFileAsync method

Область применения: надстройки области задач Word и PowerPointApplies to: Task pane add-ins for Word and PowerPoint

Метод Document.getFileAsync и члены объектов File и Slice предоставляют возможность получения целого файла документа Word и PowerPoint в виде порций (блоков) размером до 4 МБ. Дополнительные сведения см. в статье Получение всего документа из надстройки PowerPoint или Word.The Document.getFileAsync method and members of the File and Slice objects to provide functionality for getting entire Word and PowerPoint document files in slices (chunks) of up to 4 MB at a time. For more information, see Get the whole document from an add-in for PowerPoint or Word.

Объект MailboxMailbox object

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

Надстройки Outlook, в основном, используют набор API, предоставляемый через объект Mailbox. Чтобы получить объекты и члены специально для использования в надстройках Outlook, такие как объект Item, используйте свойство mailbox объекта Context для получения доступа к объекту Mailbox, как показано в следующей строке кода.Outlook add-ins primarily use a subset of the API exposed through the Mailbox object. To access the objects and members specifically for use in Outlook add-ins, such as the Item object, you use the mailbox property of the Context object to access the Mailbox object, as shown in the following line of code.

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

Кроме того, надстройки Outlook могут использовать следующие объекты:Additionally, Outlook add-ins can use the following objects:

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

  • Объект Context для получения доступа к контенту и отображения языковых свойств.Context object: for access to content and display language properties.

  • Объект RoamingSettings для сохранения пользовательских свойств, относящихся к надстройке Outlook, в почтовом ящике пользователя, в котором установлено приложение.RoamingSettings object: for saving Outlook add-in-specific custom settings to the user's mailbox where the add-in is installed.

Сведения об использовании JavaScript в надстройках Outlook см. в статье Надстройки Outlook.For information about using JavaScript in Outlook add-ins, see Outlook add-ins.