Настройка документа для запуска кода при его открытии

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

Совет

В этой статье описывается функция, позволяющая надстройке программно настроить себя для запуска кода при открытии документа. Этот метод имеет области действия документов, что означает, что его необходимо применять к каждому документу отдельно. Эта функция отличается от трех похожих функций:

  • Надстройку можно настроить в манифесте для выполнения кода при открытии любого документа. Эта функция относится к области приложений Office. После установки надстройки администратором Microsoft 365 на портале администратора клиента Microsoft 365 надстройка запускает и выполняет код для каждого документа Office, открытого в приложениях Office, для поддержки которых надстройка настроена в манифесте. Дополнительные сведения см. в разделе Активация надстроек с помощью событий, особенно информации о OnDocumentOpened событии.
  • Надстройка может программно настроить документ так, чтобы при открытии документа автоматически открывалась область задач надстройки. Эту функцию также необходимо применять к каждому документу в отдельности. Дополнительные сведения см. в статье "Автоматическое открытие области задач с документом".
  • Надстройку можно настроить в манифесте так, чтобы она открывала область задач , когда надстройка устанавливается конечным пользователем. Эта функция ограничена одним документом: тем, который был открыт при установке надстройки. Дополнительные сведения см. в статье "Автоматическое открытие области задач при установке надстройки".

Конфигурация реализована с помощью метода, который ваш код вызывает во время выполнения. Это означает, что надстройка не будет запущена при первом открытии документа. Надстройку необходимо открывать вручную в первый раз для любого документа. После выполнения метода, либо в Office.initialize, Office.onReady, либо потому, что пользователь выбирает путь кода, который его запускает; Затем при повторном открытии документа надстройка загружается немедленно и выполняется весь код в методе Office.initialize ИЛИ Office.onReady .

Примечание.

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

Важно!

Общая среда выполнения поддерживается только в некоторых приложениях Office. Дополнительные сведения см. в статье Наборы обязательных элементов общей среды выполнения.

Настройка загрузки надстройки при открытии документа

Приведенный ниже код настраивает загрузку и запуск надстройки при открытии документа.

Office.addin.setStartupBehavior(Office.StartupBehavior.load);

Примечание.

Метод setStartupBehavior асинхронный.

Поместите код запуска в Office.initialize или Office.onReady

Если надстройка настроена на загрузку при открытии документа, она будет запущена немедленно. Будет Office.initialize вызван обработчик событий. Поместите код запуска в Office.initialize обработчик события OR.Office.onReady

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

// This is called as soon as the document opens.
// Put your startup code here.
Office.initialize = () => {
  // Add the event handler.
  Excel.run(async context => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    sheet.onChanged.add(onChange);

    await context.sync();
    console.log("A handler has been registered for the onChanged event.");
  });
};

/**
 * Handle the changed event from the worksheet.
 *
 * @param event The event information from Excel
 */
async function onChange(event) {
    await Excel.run(async (context) => {    
        await context.sync();
        console.log("Change type of event: " + event.changeType);
        console.log("Address of event: " + event.address);
        console.log("Source of event: " + event.source);
  });
}

В приведенном ниже коде надстройки PowerPoint показано, как зарегистрировать обработчик событий изменения выделения в документе PowerPoint. Если надстройка настроена на загрузку при открытии документа, этот код регистрирует обработчик событий при открытии документа. Вы можете обработать события изменения до открытия области задач.

// This is called as soon as the document opens.
// Put your startup code here.
Office.onReady(info => {
  if (info.host === Office.HostType.PowerPoint) {
    Office.context.document.addHandlerAsync(Office.EventType.DocumentSelectionChanged, onChange);
    console.log("A handler has been registered for the onChanged event.");
  }
});

/**
 * Handle the changed event from the PowerPoint document.
 *
 * @param event The event information from PowerPoint
 */
async function onChange(event) {
  console.log("Change type of event: " + event.type);
}

Настройка надстройки для работы без загрузки при открытии документа

Возможны сценарии, в которых вы захотите отключить действие "запуск при открытии документа". Приведенный ниже код настраивает надстройку таким образом, чтобы она не запускалась при открытии документа. Вместо этого она запускается, когда пользователь задействует ее каким-либо образом, например, выбирает кнопку ленты или открывает область задач. Этот код не действует, если метод ранее не вызывался в текущем документе с Office.StartupBehavior.load параметром as.

Примечание.

Если надстройка вызывает метод с Office.StartupBehavior.load параметром as, in Office.initialize или Office.onReady, поведение снова включается. Таким образом, в этом сценарии отключение применяется только к следующему открытию документа, а не ко всем последующим открытиям.

Office.addin.setStartupBehavior(Office.StartupBehavior.none);

Получить текущее поведение нагрузки

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

let behavior = await Office.addin.getStartupBehavior();

См. также

  • Last updated on