Включение и отключение команд надстроек

Статья
02/14/2025

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

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

Примечание.

В этой статье предполагается, что вы знакомы с основными понятиями команд надстроек. Просмотрите ее, если вы работали с командами надстроек (настраиваемыми элементами меню и кнопками ленты) некоторое время назад.
Программное включение или отключение контекстных меню не поддерживается. Поддерживаются только кнопки ленты, меню и вкладки.

Поддержка приложений и платформ Office

Api, описанные в этой статье, доступны в Excel, PowerPoint и Word в составе набора обязательных элементов RibbonApi 1.1. Сведения о том, как протестировать поддержку платформы с наборами требований, см. в статье Версии Office и наборы требований.

Необходима общая среда выполнения

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

Установка состояния "Отключено" по умолчанию

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

Унифицированный манифест для Microsoft 365
Манифест только надстройки

Примечание.

Унифицированный манифест для Microsoft 365 можно использовать в рабочих надстройках Outlook. Он доступен только в качестве предварительной версии для надстроек Excel, PowerPoint и Word.

Просто добавьте свойство "enabled" со значением false в объект элемента управления или элемента меню. Ниже показана базовая структура.

"extensions": [
    ...
    {
        ...
        "ribbons": [
            ...
            {
                ...
                "tabs": [
                    {
                        "id": "MyTab",
                        "groups": [
                            {
                                ...
                                "controls": [
                                    {
                                        "id": "Contoso.MyButton1",
                                        ...
                                        "enabled": false
                                    }
                                ]
                            }
                        ]
                    }
                ]
            }
        ]
    }
]

Просто добавьте элемент Enabled (со значениемfalse) сразу под (не внутри) элемента Action в объявлении элемента управления. Ниже показана базовая структура.

<OfficeApp ...>
  ...
  <VersionOverrides ...>
    ...
    <Hosts>
      <Host ...>
        ...
        <DesktopFormFactor>
          <ExtensionPoint ...>
            <CustomTab ...>
              ...
              <Group ...>
                ...
                <Control ... id="Contoso.MyButton3">
                  ...
                  <Action ...>
                  <Enabled>false</Enabled>
...
</OfficeApp>

Изменение состояния программными средствами

Ниже приведены основные действия по изменению состояния включенной команды надстройки.

Создайте объект RibbonUpdaterData , который (1) указывает команду и ее родительскую группу и вкладку по идентификаторам, объявленным в манифесте; и (2) указывает состояние включенной или отключенной команды.
Перенесите объект RibbonUpdaterData в метод Office.ribbon.requestUpdate().

Ниже приведен простой пример. Обратите внимание, что myButton, OfficeAddinTab1 и CustomGroup111 копируются из манифеста.

function enableButton() {
    Office.ribbon.requestUpdate({
        tabs: [
            {
                id: "OfficeAppTab1", 
                groups: [
                    {
                      id: "CustomGroup111",
                      controls: [
                        {
                            id: "MyButton", 
                            enabled: true
                        }
                      ]
                    }
                ]
            }
        ]
    });
}

Кроме того, мы предоставляем несколько интерфейсов (типов) для упрощения создания объекта RibbonUpdateData. Ниже приводится аналогичный пример в TypeScript, в котором используются эти типы.

const enableButton = async () => {
    const button: Control = {id: "MyButton", enabled: true};
    const parentGroup: Group = {id: "CustomGroup111", controls: [button]};
    const parentTab: Tab = {id: "OfficeAddinTab1", groups: [parentGroup]};
    const ribbonUpdater: RibbonUpdaterData = { tabs: [parentTab]};
    Office.ribbon.requestUpdate(ribbonUpdater);
}

Вы можете await вызвать requestUpdate(), если родительская функция является асинхронной, но обратите внимание, что приложение Office управляет обновлением состояния ленты. Метод requestUpdate() ставит запрос на обновление в очередь. Метод разрешает объект promise сразу же, как только он помещает запрос в очередь, а не при фактическом обновлении ленты.

Изменение состояния в ответ на событие

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

Рассмотрим сценарий, в котором кнопка должна быть включена, только когда активирована диаграмма. Во-первых, задайте значение false для элемента Enabled для кнопки в манифесте. Пример см. выше.

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

Office.onReady(async () => {
    await Excel.run(context => {
        const charts = context.workbook.worksheets
            .getActiveWorksheet()
            .charts;
        charts.onActivated.add(enableChartFormat);
        charts.onDeactivated.add(disableChartFormat);
        return context.sync();
    });
});

В-третьих, определите обработчик enableChartFormat. Ниже приведен простой пример. Более надежный способ изменения состояния элемента управления см. в разделе Рекомендация: проверка на наличие ошибок в состоянии элементов управления ниже.

function enableChartFormat() {
    const button = {
        id: "ChartFormatButton", 
        enabled: true
    };
    const parentGroup = {
        id: "MyGroup",
        controls: [button]
    };
    const parentTab = {
        id: "CustomChartTab", 
        groups: [parentGroup]
    };
    const ribbonUpdater = {tabs: [parentTab]};
    Office.ribbon.requestUpdate(ribbonUpdater);
}

В-четвертых, определите обработчик disableChartFormat. Он будет идентичен enableChartFormat, только для свойства объекта кнопки enabled будет задано значение false.

Одновременное включение видимости вкладки и состояние включенной кнопки

Метод requestUpdate также используется для переключения видимости пользовательской контекстной вкладки. Дополнительные сведения об этом и примере кода см. в статье Создание пользовательских контекстных вкладок в надстройках Office.

Рекомендация: проверка на наличие ошибок в состоянии элементов управления

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

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

В приведенном ниже примере показана функция, с помощью которой можно отключить кнопку и записать ее состояние. Обратите внимание, что chartFormatButtonEnabled — глобальная логическая переменная, которая инициализируется до того же значения, что и элемент Enabled для кнопки в манифесте.

function disableChartFormat() {
    const button = {
        id: "ChartFormatButton", 
        enabled: false
    };
    const parentGroup = {
        id: "MyGroup",
        controls: [button]
    };
    const parentTab = {
        id: "CustomChartTab", 
        groups: [parentGroup]
    };
    const ribbonUpdater = {tabs: [parentTab]};
    Office.ribbon.requestUpdate(ribbonUpdater);

    chartFormatButtonEnabled = false;
}

В приведенном ниже примере показано, как обработчик кнопки проверяет ее на наличие неправильного состояния. Обратите внимание, что reportError — это функция, которая отображает или записывает в журнал ошибку.

function chartFormatButtonHandler() {
    if (chartFormatButtonEnabled) {

        // Do work here

    } else {
        // Report the error and try again to disable.
        reportError("That action is not possible at this time.");
        disableChartFormat();
    }
}

Обработка ошибок

В некоторых случаях Office не может обновить ленту и возвращает ошибку. Например, если после обновления у надстройки другой набор настраиваемых команд, приложение Office необходимо закрыть и снова открыть. Пока это действие не будет выполнено, метод requestUpdate будет возвращать ошибку HostRestartNeeded. Ниже приведен пример обработки этой ошибки. В этом случае метод reportError выводит сообщение об ошибке для пользователя.

function disableChartFormat() {
    try {
        const button = {
            id: "ChartFormatButton", 
            enabled: false
        };
        const parentGroup = {
            id: "MyGroup",
            controls: [button]
        };
        const parentTab = {
            id: "CustomChartTab", 
            groups: [parentGroup]
        };
        const ribbonUpdater = {tabs: [parentTab]};
        Office.ribbon.requestUpdate(ribbonUpdater);

        chartFormatButtonEnabled = false;
    }
    catch(error) {
        if (error.code == "HostRestartNeeded"){
            reportError("Contoso Awesome Add-in has been upgraded. Please save your work, close the Office application, and restart it.");
        }
    }
}

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