Команды надстроек для Excel, Word и PowerPointAdd-in commands for Excel, Word, and PowerPoint

Команды надстроек — это элементы, которые расширяют пользовательский интерфейс Office и запускают действия в надстройке. Команды надстроек можно использовать для добавления кнопки на ленту или элемента в контекстное меню. Когда пользователи выбирают команду надстройки, они инициируют действия, такие как запуск кода JavaScript или отображение страницы надстройки в области задач. Команды надстройки помогают пользователям находить и использовать вашу надстройку, что может повысить показатель внедрения надстройки и коэффициент удержания клиентов.Add-in commands are UI elements that extend the Office UI and start actions in your add-in. You can use add-in commands to add a button on the ribbon or an item to a context menu. When users select an add-in command, they initiate actions such as running JavaScript code, or showing a page of the add-in in a task pane. Add-in commands help users find and use your add-in, which can help increase your add-in's adoption and reuse, and improve customer retention.

Обзор этой функции приведен в видео, посвященном командам надстроек на ленте Office.For an overview of the feature, see the video Add-in Commands in the Office Ribbon.

Примечание

В каталогах SharePoint не поддерживаются команды надстроек. Последние можно развернуть с помощью компонента централизованного развертывания или AppSource. Чтобы развернуть команду надстройки для тестирования, выполните загрузку неопубликованного приложения.SharePoint catalogs do not support add-in commands. You can deploy add-in commands via Centralized Deployment or AppSource, or use sideloading to deploy your add-in command for testing.

Рисунок 1. Надстройка с командами, работающая в классическом приложении ExcelFigure 1. Add-in with commands running in Excel Desktop

Снимок экрана с командой надстройки в приложении Excel

Рисунок 2. Надстройка с командами, работающая в Excel OnlineFigure 2. Add-in with commands running in Excel Online

Снимок экрана с командой надстройки в Excel Online

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

В настоящее время поддерживаются указанные ниже возможности команд.The following command capabilities are currently supported.

Примечание

Контентные надстройки на данный момент не поддерживают команды.Content add-ins do not currently support add-in commands.

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

  • Вкладки ленты: расширение возможностей встроенных вкладок или создание пользовательской вкладки.Ribbon tabs - Extend built-in tabs or create a new custom tab.
  • Контекстные меню: расширение возможностей выбранных контекстных меню.Context menus - Extend selected context menus.

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

  • Простые кнопки, запускающие определенные действия.Simple buttons - trigger specific actions.
  • Простые раскрывающиеся меню с кнопками, которые запускают действия.Menus - simple menu dropdown with buttons that trigger actions.

ДействияActions

  • ShowTaskpane: отображает одну или несколько областей, в которые можно загрузить пользовательские HTML-страницы.ShowTaskpane - Displays one or multiple panes that load custom HTML pages inside them.
  • ExecuteFunction загружает невидимую HTML-страницу, а затем выполняет содержащуюся в ней функцию JavaScript. Для показа ошибок, хода выполнения или дополнительных данных функции можно использовать API displayDialog.ExecuteFunction - Loads an invisible HTML page and then execute a JavaScript function within it. To show UI within your function (such as errors, progress, or additional input) you can use the displayDialog API.

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

В настоящее время команды надстроек поддерживаются на следующих платформах:Add-in commands are currently supported on the following platforms:

  • Outlook 2016 для Windows (сборка 16.0.4678.1000 или более поздняя)Outlook 2016 on Windows (build 16.0.4678.1000+)
  • Office для Windows, подключенный к Office 365 (сборка 16.0.6769 или более поздняя)Office on Windows connected to Office 365 (build 16.0.6769+)
  • Office 2019 для WindowsOffice 2019 for Windows
  • Office для Mac, подключенный к Office 365 (сборка 15.33 или более поздняя)Office for Mac connected to Office 365 (build 15.33+)
  • Office 2019 для MacOffice 2019 for Mac
  • Office OnlineOffice Online

Скоро можно будет использовать другие платформы.More platforms are coming soon.

ОтладкаDebugging

Чтобы выполнить отладку команды надстройки, необходимо запустить ее в Office Online.To debug an Add-in Command, you must run it in Office Online. Дополнительные сведения см. в статье Отладка надстроек в Office OnlineFor details, see Debug add-ins in Office Online.

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

При разработке надстроек придерживайтесь следующих рекомендаций:Apply the following best practices when you develop add-in commands:

  • Каждая команда должна представлять определенное действие с очевидным и конкретным исходом для пользователей. Не совмещайте несколько действий в одной кнопке.Use commands to represent a specific action with a clear and specific outcome for users. Do not combine multiple actions in a single button.

  • Предоставляйте точные действия, которые делают выполнение распространенных задач в надстройке более эффективным. Максимально сократите количество шагов, необходимых для выполнения действия.Provide granular actions that make common tasks within your add-in more efficient to perform. Minimize the number of steps an action takes to complete.

  • Расположение команд на ленте Office:For the placement of your commands in the Office ribbon:

    • Помещайте команды на имеющиеся вкладки ("Вставка", "Рецензирование" и т. д.), если соответствующая функция подходит для них. Например, если надстройка позволяет вставлять файлы мультимедиа, добавьте группу на вкладку "Вставка". Обратите внимание, что некоторые вкладки доступны не во всех версиях Office. Дополнительные сведения см. в статье XML-манифест надстроек Office.Place commands on an existing tab (Insert, Review, and so on) if the functionality provided fits there. For example, if your add-in enables users to insert media, add a group to the Insert tab. Note that not all tabs are available across all Office versions. For more information, see Office Add-ins XML manifest.
    • Добавляйте команды на вкладку "Главная", если соответствующие функции не относятся к другим вкладкам и надстройка содержит менее шести команд верхнего уровня. Вы также можете добавлять команды на вкладку "Главная", если надстройка должна работать в разных версиях Office (например, классических приложениях Office и Office Online), а нужная вкладка доступна не во всех версиях (например, вкладка "Конструктор" отсутствует в Office Online).Place commands on the Home tab if the functionality doesn't fit on another tab, and you have fewer than six top-level commands. You can also add commands to the Home tab if your add-in needs to work across Office versions (such as Office Desktop and Office Online) and a tab is not available in all versions (for example, the Design tab doesn't exist in Office Online).
    • Добавляйте команды на пользовательскую вкладку, если надстройка содержит более шести команд верхнего уровня.Place commands on a custom tab if you have more than six top-level commands.
    • Название группы должно соответствовать названию надстройки. Если у вас есть несколько групп, их имена должны быть связаны с функциями, которые выполняют команды из этих групп.Name your group to match the name of your add-in. If you have multiple groups, name each group based on the functionality that the commands in that group provide.
    • Не добавляйте избыточные кнопки, чтобы надстройка занимала больше места на экране.Do not add superfluous buttons to increase the real estate of your add-in.

    Примечание

    Надстройки, которые занимают слишком много места, могут не пройти проверку в AppSource.Add-ins that take up too much space might not pass AppSource validation.

  • Руководство по оформлению значков подходит для всех значков.For all icons, follow the icon design guidelines.

  • Предоставьте версию надстройки, которая работает в ведущих приложениях, не поддерживающих команды.Provide a version of your add-in that also works on hosts that do not support commands. Один манифест надстройки может работать в ведущих приложениях независимо от того, поддерживают ли они команды.A single add-in manifest can work in both command-aware (with commands) and non-command-aware (as a task pane) hosts.

    Рис. 3. Надстройка области задач в Office 2013 и эта же надстройка, использующая команды надстройки в Office 2016Figure 3. Task pane add-in in Office 2013 and the same add-in using add-in commands in Office 2016

    Снимок экрана: надстройка области задач в Office 2013 и эта же надстройка, использующая команды надстройки в Office 2016

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

Лучший способ начать работу с командами надстроек Office — ознакомиться с примерами на сайте GitHub.The best way to get started using add-in commands is to take a look at the Office Add-in commands samples on GitHub.

Дополнительные сведения об указании команд надстройки в манифесте см. в статье Создание команд надстроек в манифесте и справочных материалах по VersionOverrides.For more information about specifying add-in commands in your manifest, see Create add-in commands in your manifest and the VersionOverrides reference content.