Загрузка модели DOM и среды выполненияLoading the DOM and runtime environment

Перед запуском собственной логики надстройка должна проверить, что загружены модель DOM и среда выполнения Надстройки Office.An add-in must ensure that both the DOM and the Office Add-ins runtime environment are loaded before running its own custom logic.

Запуск контентной надстройки или надстройки области задачStartup of a content or task pane add-in

На рисунке ниже приведен поток событий, происходящих при запуске контентной надстройки или надстройки области задач в Excel, PowerPoint, Project или Word.The following figure shows the flow of events involved in starting a content or task pane add-in in Excel, PowerPoint, Project, Word, or Access.

Поток событий при запуске контентной надстройки или надстройки области задач

При запуске контентной надстройки или надстройки области задач возникают указанные ниже события.The following events occur when a content or task pane add-in starts:

  1. Пользователь открывает документ, который уже содержит надстройку, или вставляет надстройку в документ.The user opens a document that already contains an add-in or inserts an add-in in the document.

  2. Ведущее приложение Office читает XML-манифест надстройки из AppSource, каталога приложений в SharePoint или каталога общей папки, в зависимости от того, откуда берется надстройка.The Office host application reads the add-in's XML manifest from AppSource, an add-in catalog on SharePoint, or the shared folder catalog it originates from.

  3. Ведущее приложение Office открывает HTML-страницу надстройки в элементе управления браузера.The Office host application opens the add-in's HTML page in a browser control.

    Следующие два действия, 4 и 5, выполняются одновременно и параллельно. Поэтому код надстройки перед обработкой должен убедиться, что и модель DOM, и среда выполнения надстройки полностью загрузились.The next two steps, steps 4 and 5, occur asynchronously and in parallel. For this reason, your add-in's code must make sure that both the DOM and the add-in runtime environment have finished loading before proceeding.

  4. Элемент управления браузера загружает модель DOM и основной текст HTML, а также вызывает обработчик для события window.onload.The browser control loads the DOM and HTML body, and calls the event handler for the window.onload event.

  5. Ведущее приложение Office загружает среду выполнения, которая загружает и кэширует API JavaScript для файлов библиотеки JavaScript с сервера сети доставки содержимого, а затем вызывает обработчик события инициализации объекта Office, если ему назначен обработчик.The Office host application loads the runtime environment, which downloads and caches the JavaScript API for JavaScript library files from the content distribution network (CDN) server, and then calls the add-in's event handler for the initialize event of the Office object, if a handler has been assigned to it. В это время также проверяется, выполнялась ли передача (или связывание) любых обратных вызовов (или связанных функций then()) обработчику Office.onReady.At this time it also checks to see if any callbacks (or chained then() functions) have been passed (or chained) to the Office.onReady handler. Дополнительные сведения о различии между Office.initialize и Office.onReady см. в статье Инициализация надстройки.For more information about the distinction between Office.initialize and Office.onReady, see Initializing your add-in.

  6. После завершения загрузки DOM и основного текста HTML и инициализации надстройки запускается основная функция надстройки.When the DOM and HTML body finish loading and the add-in finishes initializing, the main function of the add-in can proceed.

Запуск надстройки OutlookStartup of an Outlook add-in

На рисунке ниже приведен поток событий при запуске надстройки Outlook на настольном компьютере, планшетном ПК или смартфоне.The following figure shows the flow of events involved in starting an Outlook add-in running on the desktop, tablet, or smartphone.

Поток событий при запуске надстройки Outlook

При запуске надстройки Outlook происходят указанные ниже события.The following events occur when an Outlook add-in starts:

  1. При запуске Outlook считывает XML-манифесты надстроек Outlook, установленных для учетной записи пользователя.When Outlook starts, Outlook reads the XML manifests for Outlook add-ins that have been installed for the user's email account.

  2. Пользователь выбирает элемент в Outlook.The user selects an item in Outlook.

  3. Если выбранный элемент удовлетворяет условиям активации надстройки Outlook, то Outlook активирует надстройку и делает соответствующую кнопку видимой в пользовательском интерфейсе.If the selected item satisfies the activation conditions of an Outlook add-in, Outlook activates the add-in and makes its button visible in the UI.

  4. Если пользователь нажимает кнопку для запуска надстройки Outlook, то ведущее приложение открывает HTML-страницу в элементе управления браузером. Следующие два шага, шаг 5 и шаг 6, выполняются одновременно.If the user clicks the button to start the Outlook add-in, Outlook opens the HTML page in a browser control. The next two steps, steps 5 and 6, occur in parallel.

  5. Элемент управления браузером загружает DOM и основной текст HTML и вызывает обработчик события onload.The browser control loads the DOM and HTML body, and calls the event handler for the onload event.

  6. Outlook загружает среду выполнения, которая загружает и кэширует API JavaScript для файлов библиотеки JavaScript с сервера сети доставки содержимого, а затем вызывает обработчик события инициализации объекта Office надстройки, если ему назначен обработчик.Outlook loads the runtime environment, which downloads and caches the JavaScript API for JavaScript library files from the content distribution network (CDN) server, and then calls the event handler for the initialize event of the Office object of the add-in, if a handler has been assigned to it. В это время также проверяется, выполнялась ли передача (или связывание) любых обратных вызовов (или связанных функций then()) обработчику Office.onReady.At this time it also checks to see if any callbacks (or chained then() functions) have been passed (or chained) to the Office.onReady handler. Дополнительные сведения о различии между Office.initialize и Office.onReady см. в статье Инициализация надстройки.For more information about the distinction between Office.initialize and Office.onReady, see Initializing your add-in.

  7. После завершения загрузки DOM и основного текста HTML и инициализации надстройки запускается основная функция надстройки.When the DOM and HTML body finish loading and the add-in finishes initializing, the main function of the add-in can proceed.

Проверка состояния загрузкиChecking the load status

Одним из способов проверки завершения загрузки DOM и среды выполнения надстроек является использование функции .ready() jQuery — $(document).ready().One way to check that both the DOM and the runtime environment have finished loading is to use the jQuery .ready() function: $(document).ready(). Например, указанный ниже обработчик событий onReady убеждается в полной загрузке DOM, прежде чем выполняется код, относящийся к инициализации надстройки.For example, the following onReady event handler makes sure the DOM is first loaded before the code specific to initializing the add-in runs. После этого обработчик onReady переходит на использование свойства mailbox.item для получения выбранного в настоящий момент элемента Outlook и вызывает основную функцию надстройки initDialer.Subsequently, the onReady handler proceeds to use the mailbox.item property to obtain the currently selected item in Outlook, and calls the main function of the add-in, initDialer.

Office.onReady()
    .then(
        // Checks for the DOM to load.
        $(document).ready(function () {
            // After the DOM is loaded, add-in-specific code can run.
            var mailbox = Office.context.mailbox;
            _Item = mailbox.item;
            initDialer();
        });
);

Кроме того, можно использовать такой же код в обработчике событий инициализации, как показано в приведенном ниже примере.Alternatively, you can use the same code in an initialize event handler as shown in the following example.

Office.initialize = function () {
    // Checks for the DOM to load.
    $(document).ready(function () {
        // After the DOM is loaded, add-in-specific code can run.
        var mailbox = Office.context.mailbox;
        _Item = mailbox.item;
        initDialer();
    });
}

Этот же способ можно использовать в обработчиках инициализации или onReady любой надстройки Office.This same technique can be used in the onReady or initialize handlers of any Office Add-in.

В примере надстройки Outlook "Телефон" показан несколько другой подход, использующий только JavaScript для проверки тех же условий.The phone dialer sample Outlook add-in shows a slightly different approach using only JavaScript to check these same conditions.

Важно!

Даже если у надстройки нет задач инициализации, необходимо включить по крайней мере вызов обработчика Office.onReady или назначить минимальную функцию обработчика событий Office.initialize, как показано в примере ниже.Even if your add-in has no initialization tasks to perform, you must include at least a call of Office.onReady or assign minimal Office.initialize event handler function as shown in the following examples.

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

Если не вызвать Office.onReady или не назначить обработчик событий Office.initialize, надстройка может выдать ошибку при запуске.If you do not call Office.onReady or assign an Office.initialize event handler, your add-in may raise an error when it starts. Кроме того, если пользователь попробует использовать надстройку с веб-клиентом Office, например Excel, PowerPoint или Outlook, произойдет сбой.Also, if a user attempts to use your add-in with an Office Online web client, such as Excel Online, PowerPoint Online, or Outlook Web App, it will fail to run.

Если надстройка содержит несколько страниц, каждая загружаемая страница должна вызывать Office.onReady или назначать обработчик событий Office.initialize.If your add-in includes more than one page, whenever it loads a new page that page must either call Office.onReady or assign an Office.initialize event handler.

См. такжеSee also