Поделиться через

Запуск кода в надстройке Office при открытии документа

  • Статья

Важно!

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

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

Примечание.

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

Примечание.

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

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

Следующий код настраивает надстройку для загрузки и запуска при открытии документа.

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

Примечание.

Метод setStartupBehavior является асинхронным.

Размещение кода запуска в Office.initialize или Office.onReady

Если надстройка настроена для загрузки при открытии документа, она запустится немедленно. Будет Office.initialize вызван обработчик событий. Поместите код запуска в Office.initialize обработчик событий или 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 параметром .

Примечание.

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

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

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

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

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

См. также