Отображение и скрытие области задач надстройки Office

Важно!

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

Вы можете отобразить область задач надстройки Office, вызвав Office.addin.showAsTaskpane() метод .

function onCurrentQuarter() {
    Office.addin.showAsTaskpane()
    .then(function() {
        // Code that enables task pane UI elements for
        // working with the current quarter.
    });
}

В предыдущем коде предполагается сценарий, в котором есть лист Excel с именем CurrentQuarterSales. При активации этого листа надстройка сделает область задач видимой. Метод onCurrentQuarter является обработчиком события Office.Worksheet.onActivated, зарегистрированного для листа.

Вы также можете скрыть область задач, вызвав Office.addin.hide() метод .

function onCurrentQuarterDeactivated() {
    Office.addin.hide();
}

Предыдущий код является обработчиком, зарегистрированным для события Office.Worksheet.onDeactivated .

Дополнительные сведения о отображении области задач

При вызове Office.addin.showAsTaskpane()Office отобразит в области задач файл, назначенный в качестве значения идентификатора ресурса (resid) области задач. Это resid значение можно назначить или изменить, открыв файлmanifest.xml и найдя <SourceLocation> внутри <Action xsi:type="ShowTaskpane"> элемента. (Дополнительные сведения см. в разделе Настройка надстройки Office для использования общей среды выполнения .)

Так как Office.addin.showAsTaskpane() является асинхронным методом, код будет продолжать выполняться до завершения метода. Дождитесь завершения с помощью ключевого await слова или then() метода в зависимости от используемого синтаксиса JavaScript.

Настройка надстройки для использования общей среды выполнения

Чтобы использовать showAsTaskpane() методы и hide() , надстройка должна использовать общую среду выполнения. Дополнительные сведения см. в статье Настройка надстройки Office для использования общей среды выполнения.

Сохранение состояния и прослушивателей событий

Методы hide() и showAsTaskpane() изменяют только видимость области задач. Они не выгружают или не перезагружают его (или повторно инициализируют его состояние).

Рассмотрим следующий сценарий: область задач разработана с вкладками. Вкладка Главная открывается при первом запуске надстройки. Предположим, что пользователь открывает вкладку Параметры , а затем код в области задач вызывает hide() в ответ на какое-то событие. Еще позже код вызывает showAsTaskpane() в ответ на другое событие. Область задач снова появится, а вкладка Параметры по-прежнему выбрана.

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

Рассмотрим следующий сценарий: область задач имеет зарегистрированный обработчик для Excel Worksheet.onActivated и Worksheet.onDeactivated события для листа с именем Sheet1. Активированный обработчик вызывает появление зеленой точки в области задач. Деактивированный обработчик преобразует точку красным цветом (это состояние по умолчанию). Предположим, что код вызывает hide() , когда Лист 1 не активирован и точка будет красной. Пока область задач скрыта, активируется лист Sheet1 . Более поздний код вызывает showAsTaskpane() в ответ на какое-то событие. При открытии области задач точка становится зеленой, так как прослушиватели и обработчики событий выполнялись, даже если область задач была скрыта.

Обработка события изменения видимости

Когда код изменяет видимость области задач с помощью showAsTaskpane() или hide(), Office активирует VisibilityModeChanged событие. Это событие может быть полезно для обработки. Например, предположим, что в области задач отображается список всех листов книги. Если новый лист добавляется, когда область задач скрыта, то ее видимость сама по себе не добавит в список новое имя листа. Но код может ответить VisibilityModeChanged на событие, чтобы перезагрузить свойство Worksheet.name всех листов в коллекции Workbook.worksheets , как показано в примере кода ниже.

Чтобы зарегистрировать обработчик для события, не используйте метод add handler, как в большинстве контекстов JavaScript в Office. Вместо этого существует специальная функция, в которую передается обработчик: Office.addin.onVisibilityModeChanged. Ниже приведен пример. Обратите внимание, что args.visibilityMode свойство имеет тип VisibilityMode.

Office.addin.onVisibilityModeChanged(function(args) {
    if (args.visibilityMode == "Taskpane") {
        // Code that runs whenever the task pane is made visible.
        // For example, an Excel.run() that loads the names of
        // all worksheets and passes them to the task pane UI.
    }
});

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

const removeVisibilityModeHandler =
    Office.addin.onVisibilityModeChanged(function(args) {
        if (args.visibilityMode == "Taskpane") {
            // Code that runs whenever the task pane is made visible.
        }
    });


// In some later code path, deregister with:
removeVisibilityModeHandler();

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

// await the promise from onVisibilityModeChanged and assign
// the returned deregister handler to removeVisibilityModeHandler.
const removeVisibilityModeHandler =
    await Office.addin.onVisibilityModeChanged(function(args) {
        if (args.visibilityMode == "Taskpane") {
            // Code that runs whenever the task pane is made visible.
        }
    });

Отмена регистрации также является асинхронной и возвращает обещание. Таким образом, если у вас есть код, который не должен выполняться до завершения отмены регистрации, следует дождаться обещания, возвращенного функцией отмены регистрации.

// await the promise from the deregister handler before continuing
await removeVisibilityModeHandler();
// subsequent code here

См. также

• Настройка надстройки Office для использования общей среды выполнения
• Запуск кода в надстройке Office при открытии документа