Инициализация надстройки Office

  • Статья

Надстройки Office часто поддерживают логику запуска для выполнения следующих действий:

  • Убедитесь, что пользовательская версия Office поддерживает все API Office, которые вызывает ваш код.

  • Убедитесь в наличии определенных артефактов, таких как лист с определенным именем.

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

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

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

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

  • Инициализация с помощью Office.onReady().
  • Инициализация с помощью Office.initialize.

Совет

Рекомендуется использовать Office.onReady() вместо Office.initialize. Хотя Office.initialize по-прежнему поддерживается, Office.onReady() обеспечивает большую гибкость. Вы можете назначить только один обработчик Office.initialize , который вызывается инфраструктурой Office только один раз. Вы можете вызывать Office.onReady() в разных местах кода и использовать разные обратные вызовы.

Сведения о различиях описанных ниже приемов см. в статье Основные различия между Office.initialize и Office.onReady().

Дополнительные сведения о последовательности событий при инициализации надстройки см. в статье Загрузка модели DOM и среды выполнения.

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

Office.onReady() — это асинхронная функция, которая возвращает объект Promise , проверяя, загружена ли библиотека Office.js. При загрузке библиотеки она разрешает Promise как объект, указывающий клиентское приложение Office со Office.HostType значением перечисления (Excel, Word, и т. д.) и платформу Office.PlatformType со значением перечисления (PC, Mac, OfficeOnlineи т. д.). Объект Promise сопоставляется незамедлительно, если библиотека уже загружена, когда вызывается Office.onReady().

Один из способов вызова Office.onReady() — передать ему функцию обратного вызова. Ниже приведен пример.

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(), вместо того чтобы использовать обратный вызов. Например приведенный ниже код проверяет, поддерживает ли версия Excel пользователя использование API, которые может вызывать надстройка.

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.

(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(). Например, на метод JQuery$(document).ready() можно ссылаться следующим образом:

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

Однако существуют исключения для таких случаев. Например, предположим, что вы хотите открыть надстройку в браузере (а не загружать ее в приложение Office), чтобы отладить пользовательский интерфейс с помощью средств браузера. В этом сценарии, когда Office.js определит, что оно выполняется за пределами ведущего приложения Office, он вызовет обратный вызов и выполнит обещание null как для узла, так и для платформы.

Другим исключением может быть, если вы хотите, чтобы индикатор хода выполнения отображался в области задач во время загрузки надстройки. В этом сценарии код должен вызвать jQuery ready и использовать его обратный вызов для отображения индикатора хода выполнения. Затем обратный Office.onReady вызов может заменить индикатор хода выполнения конечным пользовательским интерфейсом.

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

Событие инициализации запускается, когда библиотека Office.js будет загружена и готова к взаимодействию с пользователем. Вы можете назначить обработчик Office.initialize для реализации вашей логики инициализации. Например, приведенный ниже код проверяет, поддерживает ли версия Excel пользователя использование API, которые может вызывать надстройка.

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 событие (исключения, описанные в разделе Initialize with Office.onReady() выше, также применимы в этом случае). Например, на метод JQuery$(document).ready() можно ссылаться следующим образом:

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

Для надстроек области задач и контентных надстроек Office.initialize предоставляет дополнительный параметр reason. Этот параметр определяет порядок добавления надстройки в текущий документ. Это поможет обеспечить разную логику в тех случаях, когда надстройка вставляется впервые или когда она уже существует в документе.

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.

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

  • Вы можете назначить только один обработчик для Office.initialize, который будет вызываться только один раз инфраструктурой Office, но вы можете вызывать Office.onReady() в разных местах вашего кода и использовать разные обратные вызовы. Например, ваш код может вызвать Office.onReady() сразу после загрузки настраиваемого скрипта с обратным вызовом, запускающим логику инициализации. В коде также может применяться кнопка в области задач, чей скрипт вызывает Office.onReady() с другим обратным вызовом. В этом случае второй обратный вызов запускается при нажатии кнопки.

  • Событие Office.initialize запускается в конце выполнения внутренних процессов, когда Office.js инициализирует собственное выполнение. И оно срабатывает сразу же после окончания внутренних процессов. Если код, в котором вы назначаете обработчик события, выполняется слишком долго после запуска события, тогда обработчик не запускается. Например если вы используете диспетчер задач WebPack, он может настроить домашнюю страницу надстройки для загрузки файлов полизаполнения сразу после загрузки Office.js, но перед загрузкой вашего настраиваемого скрипта JavaScript. К тому моменту, когда ваш скрипт загружается и назначает обработчика, инициализации события уже выполнена. Но никогда не "слишком поздно" вызывать Office.onReady(). Если инициализация события уже произошла, обратный вызов выполняется немедленно.

Примечание.

Даже если отсутствует логика запуска, следует вызвать Office.onReady() или назначить пустую функцию для Office.initialize, когда ваша надстройка загружает JavaScript. Некоторые сочетания приложений и платформ Office не загружаются в область задач, пока не произойдет одно из них. Эти два способа показаны в приведенных ниже примерах.

Office.onReady();

Office.initialize = function () {};

Инициализация отладки

Сведения об отладке функций и Office.onReady() см. в Office.initialize разделе Отладка функций initialize и onReady.

См. также