Изменение доступности команд надстроек

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

Поддерживаемые возможности

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

• Кнопки, меню и вкладки ленты.
• Элементы контекстного меню.

Поддержка приложений Office и набора требований

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

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

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

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

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

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

function enableButton() {
    const ribbonUpdaterData = {
        tabs: [
            {
                id: "OfficeAppTab1",
                groups: [
                    {
                      id: "CustomGroup111",
                      controls: [
                        {
                            id: "MyButton",
                            enabled: true
                        }
                      ]
                    }
                ]
            }
        ]
    };

    Office.ribbon.requestUpdate(ribbonUpdaterData);
}

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 Office.contextMenu.requestUpdate({
    controls: [
        {
            id: Addin.CtxMenu.Button1,
            enabled: true
        },
        {
            id: Addin.CtxMenu.Button2,
            enabled: false
        },
    ]
});

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

Распространенный сценарий, в котором должно измениться состояние ленты или элемента управления контекстным меню, — это когда инициируемое пользователем событие изменяет контекст надстройки. Рассмотрим сценарий, в котором кнопка должна быть доступна только при активации диаграммы. Хотя в следующем примере используются элементы управления ленты, аналогичную реализацию можно применить к пользовательским элементам в контекстном меню.

1. Сначала присвойте элементу< Enabled> для кнопки в манифесте значение false. Инструкции по настройке см. в разделе Отключение элементов управления ленты при запуске.

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

   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();
       });
   });
   

3. Определите 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);
   }
   

4. Определите disableChartFormat обработчик. Он идентичен обработчику enableChartFormat , за исключением того, что свойство enabled объекта button имеет значение false.

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

В некоторых случаях лента или контекстное меню не перекрашивали после 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 to make the button unavailable again.
        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.");
        }
    }
}

См. также

• Команды надстроек
• Создание команд надстройки с помощью манифеста только надстройки
• Создание пользовательских контекстных вкладок в надстройках Office