Создание пользовательских контекстных вкладок в надстройках Office

Статья
09/24/2024

Контекстная вкладка — это скрытый элемент управления tab на ленте Office, который отображается в строке вкладки при возникновении указанного события в документе Office. Например, вкладка "Конструктор таблиц ", которая появляется на ленте Excel при выборе таблицы. Вы включаете пользовательские контекстные вкладки в надстройку Office и указываете, когда они видны или скрыты, создавая обработчики событий, которые изменяют видимость. (Однако пользовательские контекстные вкладки не реагируют на изменения фокуса.)

Примечание.

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

Предварительные условия

Пользовательские контекстные вкладки в настоящее время поддерживаются только в Excel и только на следующих платформах и сборках.

Excel в Интернете
Excel в Windows: версия 2102 (сборка 13801.20294) и более поздние версии.
Excel на Mac: версия 16.53 (21080600) и более поздние версии.

Кроме того, пользовательские контекстные вкладки работают только на платформах, поддерживающих следующие наборы требований. Дополнительные сведения о наборах требований и способах работы с ними см . в разделе Указание приложений Office и требований к API.

Совет

Используйте проверки среды выполнения в коде, чтобы проверить, поддерживает ли сочетание узла и платформы пользователя эти наборы требований, как описано в разделе Проверка среды выполнения для поддержки методов и наборов требований. (Метод указания наборов требований в манифесте, который также описан в этой статье, в настоящее время не работает для RibbonApi 1.2.) Кроме того, можно реализовать альтернативный интерфейс пользовательского интерфейса, если пользовательские контекстные вкладки не поддерживаются.

Поведение пользовательских контекстных вкладок

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

Когда отображается пользовательская контекстная вкладка, она отображается на правом конце ленты.
Если одна или несколько встроенных контекстных вкладок и одна или несколько настраиваемых контекстных вкладок из надстроек видны одновременно, настраиваемые контекстные вкладки всегда находятся справа от всех встроенных контекстных вкладок.
Если надстройка содержит несколько контекстных вкладок и есть контексты, в которых отображается несколько, они отображаются в том порядке, в котором они определены в надстройке. (Направление совпадает с направлением языка Office. То есть слева направо в языках слева направо, но справа налево в языках справа налево.) Дополнительные сведения о том, как их определить, см. в разделе Определение групп и элементов управления, отображаемых на вкладке .
Если несколько надстроек имеют контекстные вкладки, видимые в определенном контексте, они отображаются в том порядке, в котором были запущены надстройки.
Пользовательские контекстные вкладки, в отличие от пользовательских основных вкладок, не добавляются на ленту приложения Office. Они присутствуют только в документах Office, в которых выполняется надстройка.

Предупреждение

В настоящее время использование пользовательских контекстных вкладок может помешать пользователю отменить предыдущие действия Excel. Это известная проблема (см . этот поток GitHub) и активно исследуется.

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

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

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

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

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

Указание значков для контекстной вкладки

Перед настройкой контекстной вкладки необходимо указать все значки, которые будут отображаться на ней с элементом Image в разделе Ресурсы манифеста надстройки. Каждый значок должен иметь по крайней мере три размера: 16x16 пикселей, 32x32 пикселей и 80x80 пикселей.

Ниже приведен пример.

<Resources>
    <bt:Images>
        <bt:Image id="contextual-tab-icon-16" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/Group16x16.png"/>
        <bt:Image id="contextual-tab-icon-32" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/Group32x32.png"/>
        <bt:Image id="contextual-tab-icon-80" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/Group80x80.png"/>
        <bt:Image id="contextual-button-icon-16" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton16x16.png"/>
        <bt:Image id="contextual-button-icon-32" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton32x32.png"/>
        <bt:Image id="contextual-button-icon-80" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton80x80.png"/>
    </bt:Images>
    ...
</Resources>

Важно!

При перемещении надстройки из среды разработки в рабочую среду не забудьте обновить URL-адреса в манифесте по мере необходимости (например, изменить домен с localhost на contoso.com).

Определение групп и элементов управления, отображаемых на вкладке

В отличие от пользовательских основных вкладок, которые определяются с помощью XML в манифесте, пользовательские контекстные вкладки определяются во время выполнения с помощью большого двоичного объекта JSON. Код анализирует большой двоичный объект в объект JavaScript, а затем передает объект в метод Office.ribbon.requestCreateControls . Пользовательские контекстные вкладки присутствуют только в документах, в которых сейчас выполняется надстройка. Это отличается от пользовательских основных вкладок, которые добавляются на ленту приложения Office при установке надстройки и сохраняются при открытии другого документа. Кроме того, requestCreateControls метод может выполняться только один раз в сеансе надстройки. При повторном вызове возникает ошибка.

Примечание.

Структура свойств и вложенных свойств большого двоичного объекта JSON (и имен ключей) примерно аналогична структуре элемента CustomTab и его потомков в XML-коде манифеста.

Мы создадим пример большого двоичного объекта JSON с контекстными вкладками. Полная схема json контекстной вкладки находится на dynamic-ribbon.schema.json. Если вы работаете в Visual Studio Code, этот файл можно использовать для получения IntelliSense и проверки JSON. Дополнительные сведения см. в разделе Изменение JSON с помощью Visual Studio Code — схемы и параметры JSON.

Начните с создания строки JSON с двумя свойствами массива с именами actions и tabs. Массив actions — это спецификация всех функций, которые могут выполняться элементами управления на контекстной вкладке. Массив tabs определяет одну или несколько контекстных вкладок, максимум до 20.
```
'{
  "actions": [

  ],
  "tabs": [

  ]
}'
```
Этот простой пример контекстной вкладки будет содержать только одну кнопку и, следовательно, только одно действие. Добавьте следующий элемент в качестве единственного члена массива actions . Об этой разметке обратите внимание:
- id Свойства и type являются обязательными.
- Значение type может быть либо "ExecuteFunction", либо "ShowTaskpane".
- Свойство functionName используется только в том случае, если значение равно typeExecuteFunction. Это имя функции, определенной в FunctionFile. Дополнительные сведения о FunctionFile см. в разделе Основные понятия для команд надстроек.
- На следующем шаге вы сопоставите это действие с кнопкой на контекстной вкладке.
```
{
  "id": "executeWriteData",
  "type": "ExecuteFunction",
  "functionName": "writeData"
}
```
Добавьте следующий элемент в качестве единственного члена массива tabs . Об этой разметке обратите внимание:
- Свойство id является обязательным. Используйте краткий описательный идентификатор, уникальный среди всех контекстных вкладок в надстройке.
- Свойство label является обязательным. Это удобная строка, которая служит меткой контекстной вкладки.
- Свойство groups является обязательным. Он определяет группы элементов управления, которые будут отображаться на вкладке. Он должен содержать по крайней мере один член и не более 20. (Существуют также ограничения на количество элементов управления, которые можно использовать на пользовательской контекстной вкладке, что также ограничивает количество имеющихся групп. Дополнительные сведения см. в следующем шаге.)
Примечание.

Объект tab также может иметь необязательное visible свойство, указывающее, отображается ли вкладка сразу при запуске надстройки. Так как контекстные вкладки обычно скрыты до тех пор, пока событие пользователя не активирует видимость (например, пользователь выбирает сущность определенного типа в документе), visible свойство по умолчанию имеет значение , false если его нет. В следующем разделе мы покажем, как задать свойству значение true в ответ на событие.
```
{
  "id": "CtxTab1",
  "label": "Contoso Data",
  "groups": [

  ]
}
```
В простом текущем примере контекстная вкладка содержит только одну группу. Добавьте следующий элемент в качестве единственного члена массива groups . Об этой разметке обратите внимание:
- Все свойства являются обязательными.
- Свойство id должно быть уникальным среди всех групп в манифесте. Используйте краткий описательный идентификатор, который содержит до 125 символов.
- — label это удобная строка, которая служит меткой группы.
- Значение icon свойства — это массив объектов, указывающий значки, которые группа будет иметь на ленте в зависимости от размера ленты и окна приложения Office.
- Значение controls свойства представляет собой массив объектов, указывающих кнопки и меню в группе. Должен быть хотя бы один.
Важно!

Общее количество элементов управления на всей вкладке может быть не более 20. Например, вы можете иметь 3 группы с 6 элементами управления каждый и четвертую группу с 2 элементами управления, но вы не можете иметь 4 группы с 6 элементами управления каждый.
```
{
    "id": "CustomGroup111",
    "label": "Insertion",
    "icon": [

    ],
    "controls": [

    ]
}
```
Каждая группа должна иметь значок не менее трех размеров: 16x16 пикселей, 32x32 и 80 x 80 пикселей. При необходимости можно также иметь значки размером 20x20 пикселей, 24x24, 40x40 пикселей, 48x48 пикселей и 64x64 пикселей. Office определяет, какой значок использовать, в зависимости от размера ленты и окна приложения Office. Добавьте следующие объекты в массив значков. (Если размер окна и ленты достаточно велик для отображения хотя бы одного из элементов управления в группе, значок группы вообще не отображается. Например, watch группу Стили на ленте Word при сжатии и расширении окна Word.) Об этой разметке обратите внимание:
- Оба свойства являются обязательными.
- Единица size измерения свойства — пиксели. Значки всегда квадратные, поэтому число равно высоте и ширине.
- Свойство sourceLocation указывает полный URL-адрес значка. Его значение должно соответствовать URL-адресу, указанному в элементе <Image> раздела Resources> манифеста (см. раздел Указание значков для контекстной вкладки).<
Важно!

Так же, как обычно при переходе от разработки к рабочей среде необходимо изменить URL-адреса в манифесте надстройки, необходимо также изменить URL-адреса в контекстных вкладках JSON.
```
{
    "size": 16,
    "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group16x16.png"
},
{
    "size": 32,
    "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group32x32.png"
},
{
    "size": 80,
    "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group80x80.png"
}
```
В нашем простом текущем примере группа имеет только одну кнопку. Добавьте следующий объект в качестве единственного члена массива controls . Об этой разметке обратите внимание:
- Все свойства, кроме enabled, являются обязательными.
- type указывает тип элемента управления. Значения могут быть "Button", "Menu" или "MobileButton".
- id Может содержать до 125 символов.
- actionId должен быть идентификатором действия, определенного в массиве actions . (См. шаг 1 этого раздела.)
- label — это удобная строка, которая служит меткой кнопки.
- superTip представляет богатую форму подсказки. title Свойства и являются description обязательными.
- icon указывает значки для кнопки. Здесь также применяются предыдущие замечания о значке группы.
- enabled (необязательно) указывает, включена ли кнопка при запуске контекстной вкладки. Значение по умолчанию, если оно отсутствует, — .true
```
{
    "type": "Button",
    "id": "CtxBt112",
    "actionId": "executeWriteData",
    "enabled": false,
    "label": "Write Data",
    "superTip": {
        "title": "Data Insertion",
        "description": "Use this button to insert data into the document."
    },
    "icon": [
        {
            "size": 16,
            "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton16x16.png"
        },
        {
            "size": 32,
            "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton32x32.png"
        },
        {
            "size": 80,
            "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton80x80.png"
        }
    ]
}
```

Ниже приведен полный пример большого двоичного объекта JSON.

`{
  "actions": [
    {
      "id": "executeWriteData",
      "type": "ExecuteFunction",
      "functionName": "writeData"
    }
  ],
  "tabs": [
    {
      "id": "CtxTab1",
      "label": "Contoso Data",
      "groups": [
        {
          "id": "CustomGroup111",
          "label": "Insertion",
          "icon": [
            {
                "size": 16,
                "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group16x16.png"
            },
            {
                "size": 32,
                "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group32x32.png"
            },
            {
                "size": 80,
                "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group80x80.png"
            }
          ],
          "controls": [
            {
                "type": "Button",
                "id": "CtxBt112",
                "actionId": "executeWriteData",
                "enabled": false,
                "label": "Write Data",
                "superTip": {
                    "title": "Data Insertion",
                    "description": "Use this button to insert data into the document."
                },
                "icon": [
                    {
                        "size": 16,
                        "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton16x16.png"
                    },
                    {
                        "size": 32,
                        "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton32x32.png"
                    },
                    {
                        "size": 80,
                        "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton80x80.png"
                    }
                ]
            }
          ]
        }
      ]
    }
  ]
}`

Регистрация контекстной вкладки в Office с помощью requestCreateControls

Контекстная вкладка регистрируется в Office путем вызова метода Office.ribbon.requestCreateControls . Обычно это выполняется в функции, назначенной Office.initialize или с Office.onReady помощью функции . Дополнительные сведения об этих функциях и инициализации надстройки см. в статье Инициализация надстройки Office. Однако метод можно вызвать в любое время после инициализации.

Важно!

Метод requestCreateControls может вызываться только один раз в заданном сеансе надстройки. При повторном вызове возникает ошибка.

Ниже приведен пример. Обратите внимание, что перед передачей в функцию JavaScript строку JSON необходимо преобразовать в объект JavaScript с JSON.parse помощью метода .

Office.onReady(async () => {
    const contextualTabJSON = ` ... `; // Assign the JSON string such as the one at the end of the preceding section.
    const contextualTab = JSON.parse(contextualTabJSON);
    await Office.ribbon.requestCreateControls(contextualTab);
});

Укажите контексты, когда вкладка будет отображаться с помощью requestUpdate

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

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

Office.onReady(async () => {
    const contextualTabJSON = ` ... `; // Assign the JSON string.
    const contextualTab = JSON.parse(contextualTabJSON);
    await Office.ribbon.requestCreateControls(contextualTab);

    await Excel.run(context => {
        const charts = context.workbook.worksheets
            .getActiveWorksheet()
            .charts;
        charts.onActivated.add(showDataTab);
        charts.onDeactivated.add(hideDataTab);
        return context.sync();
    });
});

Затем определите обработчики. Ниже приведен простой пример , но более надежная showDataTabверсия функции см. в статье Обработка ошибки HostRestartNeeded далее в этой статье. Вот что нужно знать об этом коде:

Office определяет время обновления состояния ленты. Метод Office.ribbon.requestUpdate помещает запрос на обновление в очередь. Метод разрешает объект, Promise как только он помещает запрос в очередь, а не при фактическом обновлении ленты.
Параметром метода requestUpdate является объект RibbonUpdaterData , который (1) указывает вкладку по идентификатору точно так, как указано в JSON , и (2) указывает видимость вкладки.
Если у вас есть несколько пользовательских контекстных вкладок, которые должны быть видны в одном контексте, просто добавьте дополнительные объекты табуляции в tabs массив.

async function showDataTab() {
    await Office.ribbon.requestUpdate({
        tabs: [
            {
                id: "CtxTab1",
                visible: true
            }
        ]});
}

Обработчик для скрытия вкладки почти идентичен, за исключением того, что он задает свойству visible значение false.

Библиотека JavaScript для Office также предоставляет несколько интерфейсов (типов), упрощая созданиеRibbonUpdateData объекта. Ниже приведена showDataTab функция в TypeScript, и она использует эти типы.

const showDataTab = async () => {
    const myContextualTab: Office.Tab = {id: "CtxTab1", visible: true};
    const ribbonUpdater: Office.RibbonUpdaterData = { tabs: [ myContextualTab ]};
    await Office.ribbon.requestUpdate(ribbonUpdater);
}

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

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

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

В следующем примере включенная кнопка находится на той же контекстной вкладке, которая становится видимой.

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

Открытие области задач из контекстных вкладок

Чтобы открыть область задач с помощью кнопки на настраиваемой контекстной вкладке, создайте действие в ФОРМАТЕ JSON с type .ShowTaskpane Затем определите кнопку со свойством actionId , присвоенным свойству id действия . Откроется область задач по умолчанию, указанная элементом <Runtime> в манифесте.

`{
  "actions": [
    {
      "id": "openChartsTaskpane",
      "type": "ShowTaskpane",
      "title": "Work with Charts",
      "supportPinning": false
    }
  ],
  "tabs": [
    {
      // some tab properties omitted
      "groups": [
        {
          // some group properties omitted
          "controls": [
            {
                "type": "Button",
                "id": "CtxBt112",
                "actionId": "openChartsTaskpane",
                "enabled": false,
                "label": "Open Charts Taskpane",
                // some control properties omitted
            }
          ]
        }
      ]
    }
  ]
}`

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

Важно!

sourceLocation Если для действия задано значение , область задач не использует общую среду выполнения. Он выполняется в новой отдельной среде выполнения.
Не более одной области задач могут использовать общую среду выполнения, поэтому не более одного действия типа ShowTaskpane могут опустить sourceLocation свойство .

`{
  "actions": [
    {
      "id": "openChartsTaskpane",
      "type": "ShowTaskpane",
      "title": "Work with Charts",
      "supportPinning": false
    },
    {
      "id": "openTablesTaskpane",
      "type": "ShowTaskpane",
      "title": "Work with Tables",
      "supportPinning": false
      "sourceLocation": "https://MyDomain.com/myPage.html"
    }
  ],
  "tabs": [
    {
      // some tab properties omitted
      "groups": [
        {
          // some group properties omitted
          "controls": [
            {
                "type": "Button",
                "id": "CtxBt112",
                "actionId": "openChartsTaskpane",
                "enabled": false,
                "label": "Open Charts Taskpane",
                // some control properties omitted
            },
            {
                "type": "Button",
                "id": "CtxBt113",
                "actionId": "openTablesTaskpane",
                "enabled": false,
                "label": "Open Tables Taskpane",
                // some control properties omitted
            }
          ]
        }
      ]
    }
  ]
}`

Локализация текста JSON

Большой двоичный объект JSON, передаваемый requestCreateControls в, не локализуется так же, как и разметка манифеста для пользовательских основных вкладок (что описано в разделе Локализация элемента управления из манифеста). Вместо этого локализация должна выполняться во время выполнения с использованием отдельных больших двоичных объектов JSON для каждого языкового стандарта. Рекомендуется использовать switch оператор, который проверяет свойство Office.context.displayLanguage . Ниже приведен пример.

function GetContextualTabsJsonSupportedLocale () {
    const displayLanguage = Office.context.displayLanguage;

        switch (displayLanguage) {
            case 'en-US':
                return `{
                    "actions": [
                        // actions omitted
                     ],
                    "tabs": [
                        {
                          "id": "CtxTab1",
                          "label": "Contoso Data",
                          "groups": [
                              // groups omitted
                          ]
                        }
                    ]
                }`;

            case 'fr-FR':
                return `{
                    "actions": [
                        // actions omitted 
                    ],
                    "tabs": [
                        {
                          "id": "CtxTab1",
                          "label": "Contoso Données",
                          "groups": [
                              // groups omitted
                          ]
                       }
                    ]
               }`;

            // Other cases omitted
       }
}

Затем код вызывает функцию для получения локализованного большого двоичного объекта, переданного requestCreateControlsв , как показано в следующем примере.

const contextualTabJSON = GetContextualTabsJsonSupportedLocale();

Ресурсы

Пример кода: создание пользовательских контекстных вкладок на ленте
Пример демонстрации контекстных вкладок сообщества

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

Создание пользовательских контекстных вкладок в надстройках Office

Предварительные условия

Поведение пользовательских контекстных вкладок

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

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

Указание значков для контекстной вкладки

Определение групп и элементов управления, отображаемых на вкладке

Регистрация контекстной вкладки в Office с помощью requestCreateControls

Укажите контексты, когда вкладка будет отображаться с помощью requestUpdate

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

Открытие области задач из контекстных вкладок

Локализация текста JSON

Рекомендации по пользовательским контекстным вкладкам

Реализация альтернативного интерфейса пользовательского интерфейса, если пользовательские контекстные вкладки не поддерживаются

Использование неконтекстуальных вкладок или элементов управления

Использование API- интерфейсов, отображающих или скрывающих область задач в указанных контекстах

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

Ресурсы

Дополнительные ресурсы