Общие сведения об интерфейсе API JavaScript для OfficeUnderstanding the JavaScript API for Office

В этой статье можно узнать об интерфейсе API JavaScript для Office и о том, как его использовать. Справочные сведения см. в разделе API JavaScript для Office. О том, как обновить файлы проекта Visual Studio до последней версии API JavaScript для Office, см. в статье Обновление версии API JavaScript для Office и файлов схемы манифеста.This article provides information about the JavaScript API for Office and how to use it. For reference information, see JavaScript API for Office. For information about updating Visual Studio project files to the most current version of the JavaScript API for Office, see Update the version of your JavaScript API for Office and manifest schema files.

Примечание

Если вы планируете опубликовать надстройку в AppSource и сделать ее доступной в интерфейсе Office, убедитесь, что она соответствует политикам проверки AppSource. Например, чтобы пройти проверку, надстройка работать на всех платформах, поддерживающих определенные вами методы. Дополнительные сведения см. в разделе 4.12 и на странице со сведениями о доступности и ведущих приложениях для надстроек Office.If you plan to publish your add-in to AppSource and make it available within the Office experience, make sure that you conform to the AppSource validation policies. For example, to pass validation, your add-in must work across all platforms that support the methods that you define (for more information, see section 4.12 and the Office Add-in host and availability page).

Ссылки на библиотеку API JavaScript для Office в надстройкеReferencing the JavaScript API for Office library in your add-in

Библиотека API JavaScript для Office состоит из файла Office.js и связанных JS-файлов ведущего приложения, например Excel-15.js и Outlook-15.js. Простейший способ сослаться на API — использовать нашу сеть доставки содержимого (CDN), добавив следующий код <script> в тег <head> страницы:The JavaScript API for Office library consists of the Office.js file and associated host application-specific .js files, such as Excel-15.js and Outlook-15.js. The simplest method of referencing the API is using our CDN by adding the following <script> to your page's <head> tag:

<script src="https://appsforoffice.microsoft.com/lib/1/hosted/Office.js" type="text/javascript"></script>

Это приведет к скачиванию и кэшированию файлов JavaScript API для Office при первой загрузке надстройки, чтобы убедиться, что она использует актуальную реализацию Office.js и сопутствующих файлов для указанной версии.This will download and cache the JavaScript API for Office files the first time your add-in loads to make sure that it is using the most up-to-date implementation of Office.js and its associated files for the specified version.

Подробные сведения о CDN Office.js, включая способы управления версиями и обратной совместимостью, см. в статье Указание ссылок на библиотеку API JavaScript для Office из сети доставки содержимого (CDN).For more details around the Office.js CDN, including how versioning and backward compatibility is handled, see Referencing the JavaScript API for Office library from its content delivery network (CDN).

Инициализация надстройкиInitializing your add-in

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

Надстройки Office часто поддерживают логику запуска для выполнения следующих действий:Office Add-ins often have start-up logic to do things such as:

  • Проверьте, что пользовательская версия Office будет поддерживать все API Office, которые вызывает ваш код.Check that the user's version of Office will support all the Office APIs that your code calls.

  • Убедитесь в наличии определенных артефактов, таких как лист с заданным именем.Ensure the existence of certain artifacts, such as worksheet with a specific name.

  • Попросите пользователя выделить некоторые ячейки в Excel, а затем вставить диаграмму с инициализацией этих выделенных значений.Prompting the user to select some cells in Excel, and then inserting a chart initialized with those selected values.

  • Установите привязки.Establish bindings.

  • Используйте API для диалогового окна Office, чтобы запрашивать у пользователя значения по умолчанию для параметров надстроек.Use the Office dialog API to prompt the user for default add-in settings values.

Но ваш код запуска не должен вызывать любой API Office.js, пока библиотека не будет загружена.But your start-up code must not call any Office.js APIs until the library is loaded. Существует два способа, с помощью которых ваш код может проверять, загружена ли библиотека.There are two ways that your code can ensure that the library is loaded. Они описаны в следующих разделах:They are described in the following sections:

Совет

Рекомендуется использовать Office.onReady() вместо Office.initialize.We recommend that you use Office.onReady() instead of Office.initialize. Хотя Office.initialize по-прежнему поддерживается, использование Office.onReady() обеспечивает дополнительную гибкость.Although Office.initialize is still supported, using Office.onReady() provides more flexibility. Вы можете назначить только один обработчик для Office.initialize, который будет вызываться только один раз инфраструктурой Office, но вы можете вызывать Office.onReady() в разных местах вашего кода и использовать разные обратные вызовы.You can assign only one handler to Office.initialize and it's called only once by the Office infrastructure, but you can call Office.onReady() in different places in your code and use different callbacks.

Сведения о различиях описанных ниже приемов см. в статье Основные различия между Office.initialize и Office.onReady().For information about the differences in these techniques, see Major differences between Office.initialize and Office.onReady().

Дополнительные сведения о последовательности событий при инициализации надстройки см. в статье Загрузка модели DOM и среды выполнения.For more details about the sequence of events when an add-in is initialized, see Loading the DOM and runtime environment.

Инициализация с использованием Office.onReady()Initialize with Office.onReady()

Office.onReady() — это асинхронный метод, который возвращает объект Promise во время проверки загрузки библиотеки Office.js.Office.onReady() is an asynchronous method that returns a Promise object while it checks to see if the Office.js library is loaded. Когда библиотека будет загружена, объект Promise сопоставляется в качестве объекта, определяющего ведущее приложение Office, с числовым значением Office.HostType (Excel, Word и т. д.), а платформа — с числовым значением Office.PlatformType (PC, Mac, OfficeOnline и т. д.).When the library is loaded, it resolves the Promise as an object that specifies the Office host application with an Office.HostType enum value (Excel, Word, etc.) and the platform with an Office.PlatformType enum value (PC, Mac, OfficeOnline, etc.). Объект Promise сопоставляется незамедлительно, если библиотека уже загружена, когда вызывается Office.onReady().The Promise resolves immediately if the library is already loaded when Office.onReady() is called.

Один из способов вызова Office.onReady() состоит в передаче ему метода обратного вызова.One way to call Office.onReady() is to pass it a callback method. Пример:Here's an example:

Office.onReady(function(info) {
    if (info.host === Office.HostType.Excel) {
        // Do Excel-specific initialization (for example, make add-in task pane's
        // appearance compatible with Excel "green").
    }
    if (info.platform === Office.PlatformType.PC) {
        // Make minor layout changes in the task pane.
    }
    console.log(`Office.js is now ready in ${info.host} on ${info.platform}`);
});

Кроме того, вы можете привязать метод then() к вызову Office.onReady(), вместо того чтобы использовать обратный вызов.Alternatively, you can chain a then() method to the call of Office.onReady(), instead of passing a callback. Например приведенный ниже код проверяет, поддерживает ли версия Excel пользователя использование API, которые может вызывать надстройка.For example, the following code checks to see that the user's version of Excel supports all the APIs that the add-in might call.

Office.onReady()
    .then(function() {
        if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
            console.log("Sorry, this add-in only works with newer versions of Excel.");
        }
    });

Вот аналогичный же пример, использующий ключевые слова async и await в TypeScript:Here is the same example using the async and await keywords in TypeScript:

(async () => {
    await Office.onReady();
    if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
        console.log("Sorry, this add-in only works with newer versions of Excel.");
    }
})();

При использовании дополнительных платформ JavaScript, включающих собственный обработчик событий инициализации или тесты, они, как правило, должны размещаться внутри ответа для Office.onReady().If you are using additional JavaScript frameworks that include their own initialization handler or tests, these should usually be placed within the response to Office.onReady(). Например, ссылка на JQuery функция $(document).ready() должна выглядеть следующим образом:For example, JQuery's $(document).ready() function would be referenced as follows:

Office.onReady(function() {
    // Office is ready
    $(document).ready(function () {
        // The document is ready
    });
});

Однако существуют исключения для таких случаев.However, there are exceptions to this practice. Предположим, например, что вы хотите открыть в браузере вашу надстройку (вместо того чтобы загружать ее в хост Office) для отладки вашего пользовательского интерфейса с помощью инструментов браузера.For example, suppose you want to open your add-in in a browser (instead of sideload it in an Office host) in order to debug your UI with browser tools. Так как Office.js не загружается в браузер, onReady не будет работать, а $(document).ready не будет работать при вызове внутри Office onReady.Since Office.js won't load in the browser, onReady won't run and the $(document).ready won't run if it's called inside the Office onReady. Другое исключение: вам потребуется индикатор выполнения, который должен отображаться в области задач при загрузке надстройки.Another exception: you want a progress indicator to appear in the task pane while the add-in is loading. В данном сценарии ваш код должен вызывать jQuery ready и использовать ее обратный вызов для отображения индикатора выполнения.In this scenario, your code should call the jQuery ready and use it's callback to render the progress indicator. Затем обратный вызов onReady Office может заменять индикатор выполнения на окончательный пользовательский интерфейс Then the Office onReady's callback can replace the progress indicator with the final UI.

Инициализация с использованием Office.initializeInitialize with Office.initialize

Событие инициализации запускается, когда библиотека Office.js будет загружена и готова к взаимодействию с пользователем.An initialize event fires when the Office.js library is loaded and ready for user interaction. Вы можете назначить обработчик Office.initialize для реализации вашей логики инициализации.You can assign a handler to Office.initialize that implements your initialization logic. Например, приведенный ниже код проверяет, поддерживает ли версия Excel пользователя использование API, которые может вызывать надстройка.The following is an example that checks to see that the user's version of Excel supports all the APIs that the add-in might call.

Office.initialize = function () {
    if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
        console.log("Sorry, this add-in only works with newer versions of Excel.");
    }
};

При использовании дополнительных платформ JavaScript, включающих собственные обработчики событий инициализации или тесты, они, как правило, должны размещаться внутри события Office.initialize.If you are using additional JavaScript frameworks that include their own initialization handler or tests, these should usually be placed within the Office.initialize event. (Исключения, описанные в разделеИнициализация с помощью Office.onReady() ранее действуют и в этом случае). Например, на JQuery функцию $(document).ready() нужно сослаться следующим образом:(But the exceptions described in the Initialize with Office.onReady() section earlier apply in this case also.) For example, JQuery's $(document).ready() function would be referenced as follows:

Office.initialize = function () {
    // Office is ready
    $(document).ready(function () {
        // The document is ready
    });
  };

Для надстроек области задач и контентных надстроек Office.initialize предоставляет дополнительный параметр reason.For task pane and content add-ins, Office.initialize provides an additional reason parameter. Этот параметр определяет порядок добавления надстройки в текущий документ.This parameter specifies how an add-in was added to the current document. Это поможет обеспечить разную логику в тех случаях, когда надстройка вставляется впервые или когда она уже существует в документе.You can use this to provide different logic for when an add-in is first inserted versus when it already existed within the document.

Office.initialize = function (reason) {
    $(document).ready(function () {
        switch (reason) {
            case 'inserted': console.log('The add-in was just inserted.');
            case 'documentOpened': console.log('The add-in is already part of the document.');
        }
    });
 };

Дополнительные сведения см. в статьях Событие Office.initialize и Перечисление InitializationReason.For more information, see Office.initialize Event and InitializationReason Enumeration.

Основные различия между Office.initialize и Office.onReadyMajor differences between Office.initialize and Office.onReady

  • Вы можете назначить только один обработчик для Office.initialize, который будет вызываться только один раз инфраструктурой Office, но вы можете вызывать Office.onReady() в разных местах вашего кода и использовать разные обратные вызовы.You can assign only one handler to Office.initialize and it's called only once by the Office infrastructure; but you can call Office.onReady() in different places in your code and use different callbacks. Например, ваш код может вызвать Office.onReady() сразу после загрузки настраиваемого скрипта с обратным вызовом, запускающим логику инициализации. В коде также может применяться кнопка в области задач, чей скрипт вызывает Office.onReady() с другим обратным вызовом.For example, your code could call Office.onReady() as soon as your custom script loads with a callback that runs initialization logic; and your code could also have a button in the task pane, whose script calls Office.onReady() with a different callback. В этом случае второй обратный вызов запускается при нажатии кнопки.If so, the second callback runs when the button is clicked.

  • Событие Office.initialize запускается в конце выполнения внутренних процессов, когда Office.js инициализирует собственное выполнение.The Office.initialize event fires at the end of the internal process in which Office.js initializes itself. И оно срабатывает сразу же после окончания внутренних процессов.And it fires immediately after the internal process ends. Если код, в котором вы назначаете обработчик события, выполняется слишком долго после запуска события, тогда обработчик не запускается.If the code in which you assign a handler to the event executes too long after the event fires, then your handler doesn't run. Например если вы используете диспетчер задач WebPack, он может настроить домашнюю страницу надстройки для загрузки файлов полизаполнения сразу после загрузки Office.js, но перед загрузкой вашего настраиваемого скрипта JavaScript.For example, if you are using the WebPack task manager, it might configure the add-in's home page to load polyfill files after it loads Office.js but before it loads your custom JavaScript. К тому моменту, когда ваш скрипт загружается и назначает обработчика, инициализации события уже выполнена.By the time your script loads and assigns the handler, the initialize event has already happened. Но никогда не «поздно» выполнить вызов Office.onReady().But it is never "too late" to call Office.onReady(). Если инициализация события уже произошла, обратный вызов выполняется немедленно.If the initialize event has already happened, the callback runs immediately.

Примечание

Даже если отсутствует логика запуска, следует вызвать Office.onReady() или назначить пустую функцию для Office.initialize, когда ваша надстройка загружает JavaScript.Even if you have no start-up logic, you should either call Office.onReady() or assign an empty function to Office.initialize when your add-in JavaScript loads. Некоторые ведущие приложения Office и сочетания платформ не загружают область задач, пока не произойдет одно из этих событий.Some Office host and platform combinations won't load the task pane until one of these happens. Эти два способа показаны в приведенных ниже примерах.The following examples show these two approaches.

Office.onReady();
Office.initialize = function () {};

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

После инициализации надстройка может взаимодействовать с хостом (например, Excel, Outlook).Once initialized, the add-in can interact with the host (e.g. Excel, Outlook). Страница объектной модели Office JavaScript API содержит дополнительную информацию об определенных способах использования.The Office JavaScript API object model page has more details on specific usage patterns. Также существует подробная справочная документация для общих API и API для определенных ведущих приложений.There is also detailed reference documentation for both Common APIs and host-specific APIs.