Команды надстроек

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

Примечание.

• Каталоги SharePoint не поддерживают команды надстроек. Команды надстроек можно развернуть с помощью портала интегрированных приложений или Microsoft Marketplace или использовать загрузку неопубликованных приложений для развертывания команды надстройки для тестирования.
• Контентные надстройки на данный момент не поддерживают команды надстроек.

Типы команд надстроек

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

• Команды области задач. Кнопка или пункт меню открывает область задач надстройки. Этот тип команды надстройки добавляется с разметкой в манифесте. "Код программной части" команды предоставляется Office.

• Команды функций: кнопка или элемент меню запускает любой произвольный JavaScript. Код почти всегда вызывает API в библиотеке JavaScript для Office, но это не обязательно. Этот тип надстройки обычно не отображает пользовательский интерфейс, кроме самой кнопки или элемента меню. Обратите внимание на следующие сведения о командах функций:

  • Среда выполнения, в которой выполняется команда функции, представляет собой полную среду выполнения на основе браузера. Она может отображать HTML и обращаться к Интернету для отправки или получения данных.

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

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

    Примечание.

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

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

  Совет

  Команды функций — это не единственный способ запуска произвольного Кода JavaScript в надстройке. Надстройка также может включать:

  • Пользовательские обработчики для определенных событий, например пользователь, открывающий новую область сообщений в Outlook.
  • Пользовательские агенты Copilot , которые выполняют действия в ответ на запросы естественного языка от пользователей надстройки.

Расположение команд надстроек

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

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

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

Excel, PowerPoint и Word

Ниже показан пример команд надстроек в настраиваемой группе на вкладке Данные ленты Excel.

Outlook

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

Раскрывающееся меню

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

Команды сгруппированных надстроек на ленте

На ленте можно сгруппировать несколько команд надстроек. Группа должна содержать по крайней мере одну команду надстройки в виде кнопки или раскрывающегося меню. В Office в Windows и на Mac для команд надстроек в группе обычно отображаются метка и значок кнопки или раскрывающегося меню. Однако размер значка и видимость метки могут отличаться из-за следующих факторов, ограничивающих пространство.

• Количество команд надстройки в группе.
• Размер клиентского окна Office.

Если окно клиента развернуто и в группе имеется более трех элементов управления, отображается метка каждого элемента управления, но размер его значка может отличаться (некоторые из них отображаются как 16 x 16 пикселей, а другие — как 32 x 32 пикселя).

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

1. Для каждой команды надстройки в группе отображаются небольшие значки (16 x 16 пикселей) и метки.
2. Отображаются только небольшие значки.
3. Группа отображается в раскрывающемся меню вместо отдельных команд надстройки на ленте. На ленте также отображается значок ползунка прокрутки, что позволяет прокручивать ленту.

В Office в Интернете размер значка и видимость меток элементов управления в группах не меняются при изменении размера окна браузера. Значок ползунка прокрутки просто отображается на ленте.

Возможности команд

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

Точки расширения

• Вкладки ленты— расширение встроенных вкладок или создание пользовательской основной вкладки. Надстройка может иметь только одну пользовательскую базовую вкладку. (Команды надстроек также можно поместить на настраиваемую контекстную вкладку.)

  Примечание.

  В Outlook настраиваемые вкладки поддерживаются только в классической версии Outlook в Windows. В Outlook в Интернете, на Компьютере Mac и в новом Outlook в Windows можно разместить настраиваемые группы элементов управления на одной из встроенных вкладок ленты.

• Контекстные меню: расширение возможностей выбранных контекстных меню.

Типы элементов управления

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

Состояние доступности по умолчанию

Можно указать, доступна ли команда при запуске надстройки, и программно изменить параметр.

Примечание.

Эта функция поддерживается не во всех приложениях и сценариях Office. Дополнительные сведения см. в разделе Изменение доступности команд надстройки.

Положение на ленте

Вы можете указать, где настраиваемая вкладка будет отображаться на ленте приложения Office, например "справа от вкладки «Главная»".

Примечание.

Эта функция поддерживается не во всех приложениях и сценариях Office. Дополнительные сведения см. в статье Расположение настраиваемой вкладки на ленте.

Интеграция встроенных кнопок Office

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

Примечание.

Эта функция поддерживается не во всех приложениях и сценариях Office. Дополнительные сведения см. в статье Интеграция встроенных кнопок Office в настраиваемые вкладки.

контекстные вкладки;

Можно указать настраиваемую контекстную вкладку; то есть вкладка, которая отображается на ленте только в определенных контекстах, например при выборе диаграммы в Excel.

Примечание.

Эта функция поддерживается не во всех приложениях и сценариях Office. Дополнительные сведения см. в статье Создание пользовательских контекстных вкладок в надстройках Office.

Поддерживаемые платформы

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

• Office в Интернете
• Office в Windows, подключенный к подписке На Microsoft 365
• Office на Mac, подключенный к подписке Microsoft 365
• Бессрочная Office 2021 или более поздней версии в Windows или mac

Примечание.

Сведения о поддержке в Outlook см. в заметках о поддержке Outlook.

Отладка

Чтобы выполнить отладку команды надстройки, ее необходимо выполнить в Office в Интернете. Дополнительные сведения см. в статье Отладка надстроек в Office в Интернете

Рекомендации

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

• Каждая команда должна представлять определенное действие с очевидным и конкретным исходом для пользователей. Не объединяйте несколько действий в одной кнопке.
• Предоставляйте точные действия, которые делают выполнение распространенных задач в надстройке более эффективным. Максимально сократите количество шагов, необходимых для выполнения действия.
• Руководство по оформлению значков подходит для всех значков.
• Укажите версию надстройки, которая работает в приложениях Office или платформах (например, iPad), которые не поддерживают команды. Для этих версий можно использовать один манифест надстройки.

Рекомендации по командам надстроек на ленте

В следующей таблице описаны рекомендуемые ограничения для объектов на ленте приложения Office.

Объект	Рекомендуемое ограничение	Обоснование удобства использования
Вкладки	Семь видимых вкладок за раз	Предотвращает перегрузку пользователей с большим количеством параметров и помогает им запомнить, где находятся команды. Мы рекомендуем использовать контекстные вкладки для уменьшения беспорядка.
Группы на вкладке	Шесть групп	Помогает пользователям быстро сканировать и находить команды.
Команды на группу	Семь команд	Уменьшает усталость от принятия решений из-за слишком большого количества вариантов.
Всего команд на ленте	70 видимых команд	Помогает пользователям эффективно находить действия. Если надстройка содержит более 70 команд, рекомендуется реализовать коллекции, раскрывающиеся меню или диалоговые окна для переполнения.

Помимо рекомендуемых ограничений объектов при настройке команд надстроек на ленте следует учитывать следующее.

• Разместите команды на существующей вкладке, например на вкладках Вставка и Рецензирование, если в нее вмещается функциональность. Например, если надстройка позволяет пользователям вставлять мультимедиа, добавьте группу на вкладку Вставка. Обратите внимание, что не все вкладки доступны во всех версиях Office. Дополнительные сведения см. в разделе Манифест надстроек Office.
• Добавляйте команды на вкладку "Главная", если соответствующие функции не относятся к другим вкладкам и надстройка содержит менее шести команд верхнего уровня. Вы также можете добавить команды на вкладку Главная, если надстройка должна работать в разных версиях Office (например, Office в Интернете или на рабочем столе), а вкладка доступна не во всех версиях.
• Добавляйте команды на пользовательскую вкладку, если надстройка содержит более шести команд верхнего уровня.
• Название группы должно соответствовать названию надстройки. Если у вас есть несколько групп, их имена должны быть связаны с функциями, которые выполняют команды из этих групп.
• Убедитесь, что группы правильно свернуты при изменении размера окна приложения Office. Хотя лента предлагает динамическое изменение размера (см. статью Команды сгруппированных надстроек на ленте), необходимо также определить сочетания групп для надстройки.
• Не добавляйте ненужные кнопки, чтобы увеличить объем недвижимости надстройки.
• Не расположите настраиваемую вкладку слева от вкладки Главная и не фокусируйте ее по умолчанию при открытии документа, если только надстройка не является основным способом взаимодействия пользователей с документом. Чрезмерное выделение вашей надстройки создает неудобства и раздражает пользователей и администраторов.
• Если надстройка является основным способом взаимодействия пользователей с документом и у вас есть настраиваемая вкладка ленты, рассмотрите возможность интеграции кнопок во вкладку для применения функций Office, которые часто требуются пользователям.
• Если функции, предоставляемые настраиваемой вкладкой, должны быть доступны только в определенных контекстах, используйте настраиваемые контекстные вкладки. Если вы используете настраиваемые контекстные вкладки, реализуйте резервный интерфейс, когда ваша надстройка запускается на платформах, не поддерживающих настраиваемые контекстные вкладки.
• Реализуйте диалоговое окно для предоставления пользователям дополнительных параметров. Это не позволит надстройке перегружать ленту редко используемыми командами. Сведения о реализации диалогового окна см. в статье Использование API диалога Office в надстройках Office.

Примечание.

Надстройки, которые занимают слишком много места, могут не пройти проверку Microsoft Marketplace.

Дальнейшие действия

Лучший способ начать работу с командами надстроек Office — ознакомиться с примерами на сайте GitHub.

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

Дополнительные сведения об указании команд надстроек в унифицированном манифесте для Microsoft 365 см. в статье Создание команд надстроек с помощью унифицированного манифеста для Microsoft 365.