Создание команд надстроек в манифесте для Excel, Word и PowerPointCreate add-in commands in your manifest for Excel, Word, and PowerPoint

Используйте элемент VersionOverrides в манифесте, чтобы определить команды надстроек для Excel, Word и PowerPoint. Команды надстроек позволяют легко настроить пользовательский интерфейс Office по умолчанию, добавив конкретные элементы интерфейса, выполняющие действия. С помощью команд надстройки можно следующее:Use VersionOverrides in your manifest to define add-in commands for Excel, Word, and PowerPoint. Add-in commands provide an easy way to customize the default Office user interface (UI) with specified UI elements that perform actions. You can use add-in commands to:

  • Создавать элементы пользовательского интерфейса или точки входа, которые упрощают использование функций надстройки.Create UI elements or entry points that make your add-in's functionality easier to use.

  • Добавлять кнопки или раскрывающийся список кнопок на ленту.Add buttons or a drop-down list of buttons to the ribbon.

  • Добавлять отдельные элементы меню, каждый из которых может содержать необязательное подменю, к определенным контекстным меню.Add individual menu items — each containing optional submenus — to specific context (shortcut) menus.

  • Выполнять действия при выборе команды надстройки. Варианты действий:Perform actions when your add-in command is chosen. You can:

    • Показать пользователю одну или несколько надстроек области задач. В надстройке области задач может отображаться код HTML, использующий Office UI Fabric для создания пользовательского интерфейса.Show one or more task pane add-ins for users to interact with. Inside your task pane add-in, you can display HTML that uses Office UI Fabric to create a custom UI.

      илиor

    • Запустить код JavaScript, который обычно выполняется без отображения пользовательского интерфейса.Run JavaScript code, which normally runs without displaying any UI.

В этой статье описывается, как отредактировать манифест, чтобы задать команды надстройки. На следующей схеме показана иерархия элементов, используемых для задания команд надстройки. Эти элементы подробнее рассматриваются в этой статье.This article describes how to edit your manifest to define add-in commands. The following diagram shows the hierarchy of elements used to define add-in commands. These elements are described in more detail in this article.

На приведенном ниже изображении представлен обзор элементов команд надстройки в манифесте. Обзор элементов команд надстройки в манифестеThe following image is an overview of add-in commands elements in the manifest. Overview of add-in commands elements in the manifest

Этап 1. Ознакомление с примеромStep 1: Start from a sample

Настоятельно рекомендуем сначала ознакомиться с одним из примеров, доступных на странице с примерами команд для надстроек Office. При необходимости вы можете создать свой манифест, следуя приведенным в руководстве инструкциям. Проверить манифест можно с использованием XSD-файла на сайте с примерами команд для надстроек Office. Прежде чем приступать к использованию команд надстроек, прочтите статью Команды надстроек для Excel, Word и PowerPoint.We strongly recommend that you start from one of the samples we provide in Office Add-in Commands Samples. Optionally, you can create your own manifest by following the steps in this guide. You can validate your manifest using the XSD file in the Office Add-in Commands Samples site. Ensure that you have read Add-in commands for Excel, Word and PowerPoint before using add-in commands.

Этап 2. Создание надстройки области задачStep 2: Create a task pane add-in

Чтобы приступить к использованию команд надстройки, сначала необходимо создать надстройку области задач, а затем изменить ее манифест, как описано в этой статье. Команды надстроек невозможно использовать с контентными надстройками. Если вы обновляете существующий манифест, добавьте в манифест нужные пространства имен XML, а также элемент VersionOverrides, как описано в разделе Шаг 3. Добавление элемента VersionOverrides.To start using add-in commands, you must first create a task pane add-in, and then modify the add-in's manifest as described in this article. You can't use add-in commands with content add-ins. If you're updating an existing manifest, you must add the appropiate XML namespaces as well as add the VersionOverrides element to the manifest as described in Step 3: Add VersionOverrides element.

Ниже приведен пример манифеста надстройки Office 2013. В этом манифесте нет команд надстройки, так как здесь отсутствует элемент VersionOverrides. Office 2013 не поддерживает команды надстройки, но при добавлении элемента VersionOverrides в этот манифест надстройка будет работать как в Office 2013, так и в Office 2016. В Office 2013, надстройка не отображает команды и использует значение SourceLocation для запуска надстройки в виде единой области задач. В Office 2016, если элемент VersionOverrides не включен, для запуска надстройки используется элемент SourceLocation. Однако при включении элемента VersionOverrides надстройка отображает только команды, но не отображает надстройку в виде единой области задач.The following example shows an Office 2013 add-in's manifest. There are no add-in commands in this manifest because there is no VersionOverrides element. Office 2013 doesn't support add-in commands, but by adding VersionOverrides to this manifest, your add-in will run in both Office 2013 and Office 2016. In Office 2013, your add-in won't display add-in commands, and uses the value of SourceLocation to run your add-in as a single task pane add-in. In Office 2016, if no VersionOverrides element is included, SourceLocation is used to run your add-in. If you include VersionOverrides, however, your add-in displays the add-in commands only, and doesn't display your add-in as a single task pane add-in.

<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0" xmlns:ov="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="TaskPaneApp">
  <!--IMPORTANT! Id must be unique for each add-in. If you copy this manifest ensure that you change this id to your own GUID. -->
  <Id>657a32a9-ab8a-4579-ac9f-df1a11a64e52</Id>
  <Version>1.0.0.0</Version>
  <ProviderName>Contoso</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="Contoso Add-in Commands" />
  <Description DefaultValue="Contoso Add-in Commands"/>
  <IconUrl DefaultValue="~remoteAppUrl/Images/Icon_32.png" />
  <SupportUrl DefaultValue="[Insert the URL of a page that provides support information for the app]" />
  <AppDomains>
    <AppDomain>AppDomain1</AppDomain>
    <AppDomain>AppDomain2</AppDomain>
    <AppDomain>AppDomain3</AppDomain>
  </AppDomains>
  <Hosts>
    <Host Name="Workbook" />
  </Hosts>
  <DefaultSettings>
    <SourceLocation DefaultValue="https://www.contoso.com/Pages/Home.aspx" />
  </DefaultSettings>
  <Permissions>ReadWriteDocument</Permissions>

 <!-- The VersionOverrides element is inserted at this location in the manifest. -->

</OfficeApp>

Этап 3. Добавление элемента VersionOverridesStep 3: Add VersionOverrides element

Элемент VersionOverrides — это корневой элемент, содержащий определение команды надстройки. Элемент манифеста VersionOverrides является дочерним для элемента OfficeApp. В приведенной ниже таблице перечислены атрибуты элемента VersionOverrides.The VersionOverrides element is the root element that contains the definition of your add-in command. VersionOverrides is a child element of the OfficeApp element in the manifest. The following table lists the attributes of the VersionOverrides element.

АтрибутAttribute ОписаниеDescription
xmlnsxmlns
Обязательный.Required. Расположение схемы. Необходимое значение — http://schemas.microsoft.com/office/taskpaneappversionoverrides.The schema location, which must be http://schemas.microsoft.com/office/taskpaneappversionoverrides.
xsi:typexsi:type
Обязательный атрибут. Версия схемы. В этой статье описывается версия VersionOverridesV1_0.Required. The schema version. The version described in this article is "VersionOverridesV1_0".

В приведенной ниже таблице показаны дочерние элементы VersionOverrides.The following table identifies the child elements of VersionOverrides.

ЭлементElement ОписаниеDescription
ОписаниеDescription
Необязательный параметр. Описывает надстройку. Дочерний элемент Description переопределяет предыдущий элемент Description в родительской части манифеста. Атрибут resid для элемента Description задан как id элемента String. Элемент String содержит текст для элемента Description. Optional. Describes the add-in. This child Description element overrides a previous Description element in the parent portion of the manifest. The resid attribute for this Description element is set to the id of a String element. The String element contains the text for Description.
RequirementsRequirements
Необязательный параметр. Задает минимальные набор требований и версию библиотеки Office.js, необходимые надстройке. Дочерний элемент Requirements переопределяет элемент Requirements в родительской части манифеста. Дополнительные сведения см. в статье Указание требований касательно API и узлов Office. Optional. Specifies the minimum requirement set and version of Office.js that the add-in requires. This child Requirements element overrides the Requirements element in the parent portion of the manifest. For more information, see Specify Office hosts and API requirements.
HostsHosts
Обязательный. Задает набор узлов Office. Дочерний элемент Hosts переопределяет элемент Hosts в родительской части манифеста. Необходимо включить атрибут xsi:type, для которого задано значение "Книга" или "Документ". Required. Specifies a collection of Office hosts. The child Hosts element overrides the Hosts element in the parent portion of the manifest. You must include a xsi:type attribute set to "Workbook" or "Document".
ResourcesResources
Определяет коллекцию ресурсов (строк, URL-адресов и изображений), на которые ссылаются другие элементы манифеста. Например, значение элемента Description ссылается на дочерний элемент в элементе Resources. Элемент Resources описан в разделе Этап 7. Добавление элемента Resources далее в этой статье. Defines a collection of resources (strings, URLs, and images) that other manifest elements reference. For example, the Description element's value refers to a child element in Resources. The Resources element is described in Step 7: Add the Resources element later in this article.

В приведенном ниже примере показано, как использовать элемент VersionOverrides и его дочерние элементы.The following example shows how to use the VersionOverrides element and its child elements.

<OfficeApp>
...
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
    <Description resid="residDescription" />
    <Requirements>
      <!-- add information about requirement sets -->
    </Requirements>
    <Hosts>
      <Host xsi:type="Workbook">
        <!-- add information about form factors -->
      </Host>
      <Host xsi:type="Document">
        <!-- add information about form factors -->
      </Host>
    </Hosts>
    <Resources> 
      <!-- add information about resources -->
    </Resources>
  </VersionOverrides>
...
</OfficeApp>

Этап 4. Добавление элементов Hosts, Host и DesktopFormFactorStep 4: Add Hosts, Host, and DesktopFormFactor elements

Элемент Hosts содержит один или несколько элементов Host. Элемент Host задает конкретный узел Office. Элемент Host содержит дочерние элементы, определяющие команды надстройки, которые отображаются после установки надстройки в соответствующем узле Office. Для отображения тех же команд надстройки в нескольких различных узлах Office, необходимо продублировать дочерние элементы в каждом из элементов Host.The Hosts element contains one or more Host elements. A Host element specifies a particular Office host. The Host element contains child elements that specify the add-in commands to display after your add-in is installed in that Office host. To show the same add-in commands in two or more different Office hosts, you must duplicate the child elements in each Host.

Элемент DesktopFormFactor задает параметры надстройки, работающей в Office в Интернете (в браузере) и Windows.The DesktopFormFactor element specifies the settings for an add-in that runs in Office on Windows desktop, and Office Online (in browser).

Ниже приведены примеры элементов Hosts, Host и DesktopFormFactor.The following is an example of Hosts, Host, and DesktopFormFactor elements.

<OfficeApp>
...
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
  ...
    <Hosts>
      <Host xsi:type="Workbook">
        <DesktopFormFactor>

              <!-- information about FunctionFile and ExtensionPoint -->

        </DesktopFormFactor>
      </Host>
    </Hosts>
  ...
  </VersionOverrides>
...
</OfficeApp>

Этап 5. Добавление элемента FunctionFileStep 5: Add the FunctionFile element

Элемент FunctionFile задает файл, который содержит код JavaScript, выполняемый, когда команда надстройки использует действие ExecuteFunction (описание см. в разделе Элементы управления "Кнопка"). В атрибуте resid элемента FunctionFile указан HTML-файл, включающий все файлы JavaScript, необходимые командам надстройки. Ссылаться непосредственно на файл JavaScript невозможно. Вы можете сослаться только на HTML-файл. Имя файла задано в дочернем элементе Url элемента Resources.The FunctionFile element specifies a file that contains JavaScript code to run when an add-in command uses the ExecuteFunction action (see Button controls for a description). The FunctionFile element's resid attribute is set to a HTML file that includes all the JavaScript files your add-in commands require. You can't link directly to a JavaScript file. You can only link to an HTML file. The file name is specified as a Url element in the Resources element.

Ниже приведен пример элемента FunctionFile.The following is an example of the FunctionFile element.

<DesktopFormFactor>
    <FunctionFile resid="residDesktopFuncUrl" />
    <ExtensionPoint xsi:type="PrimaryCommandSurface">
      <!-- information about this extension point -->
    </ExtensionPoint> 

    <!-- You can define more than one ExtensionPoint element as needed -->
</DesktopFormFactor>

Важно!

Убедитесь, что код JavaScript вызывает Office.initialize.Make sure your JavaScript code calls Office.initialize.

JavaScript должен вызывать Office.initialize в HTML-файле, на который ссылается элемент FunctionFile. Элемент FunctionName (описание см. в разделе Элементы управления "Кнопка") использует функции в элементе FunctionFile.The JavaScript in the HTML file referenced by the FunctionFile element must call Office.initialize. The FunctionName element (see Button controls for a description) uses the functions in FunctionFile.

Приведенный ниже пример кода показывает, как внедрить функцию, используемую элементом FunctionName.The following code shows how to implement the function used by FunctionName.


<script>
    // The initialize function must be run each time a new page is loaded.
    (function () {
        Office.initialize = function (reason) {
            // If you need to initialize something you can do so here.
        };
    })();

    // Your function must be in the global namespace.
    function writeText(event) {

        // Implement your custom code here. The following code is a simple example.  
        Office.context.document.setSelectedDataAsync("ExecuteFunction works. Button ID=" + event.source.id,
            function (asyncResult) {
                var error = asyncResult.error;
                if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                    // Show error message.
                }
                else {
                    // Show success message.
                }
            });

        // Calling event.completed is required. event.completed lets the platform know that processing has completed. 
        event.completed();
    }
</script>

Важно!

Вызов event.completed свидетельствует, что событие успешно обработано. Если функция вызывается несколько раз, например при выборе одной команды надстройки несколько раз, все события автоматически помещаются в очередь. Первое событие запускается автоматически, тогда как остальные ожидают в очереди. Как только функция вызывает event.completed, для нее запускается следующий вызов из очереди. Если объект event.completed не реализован, функция не запускается.The call to event.completed signals that you have successfully handled the event. When a function is called multiple times, such as multiple clicks on the same add-in command, all events are automatically queued. The first event runs automatically, while the other events remain on the queue. When your function calls event.completed, the next queued call to that function runs. You must implement event.completed, otherwise your function will not run.

Этап 6. Добавление элементов ExtensionPointStep 6: Add ExtensionPoint elements

Элемент ExtensionPoint определяет, где в пользовательском интерфейсе Office должны появиться команды надстройки. Вы можете определить элементы ExtensionPoint по этим значениям xsi:type:The ExtensionPoint element defines where add-in commands should appear in the Office UI. You can define ExtensionPoint elements with these xsi:type values:

  • PrimaryCommandSurface, которое обозначает ленту в Office.PrimaryCommandSurface, which refers to the ribbon in Office.

  • ContextMenu — контекстное меню, которое появляется при нажатии правой кнопкой мыши в пользовательском интерфейсе Office.ContextMenu, which is the shortcut menu that appears when you right-click in the Office UI.

В приведенных ниже примерах показано, как применять элемент ExtensionPoint со значениями атрибута PrimaryCommandSurface и ContextMenu, и какие дочерние элементы использовать с каждым из них.The following examples show how to use the ExtensionPoint element with PrimaryCommandSurface and ContextMenu attribute values, and the child elements that should be used with each.

Важно!

Для элементов, содержащих атрибут идентификатора, необходимо предоставить уникальный идентификатор. Рекомендуем указать название компании с идентификатором. Используйте, например, формат <CustomTab id="mycompanyname.mygroupname">.For elements that contain an ID attribute, make sure you provide a unique ID. We recommend that you use your company's name along with your ID. For example, use the following format: <CustomTab id="mycompanyname.mygroupname">.

<ExtensionPoint xsi:type="PrimaryCommandSurface">
  <CustomTab id="Contoso Tab">
  <!-- If you want to use a default tab that comes with Office, remove the above CustomTab element, and then uncomment the following OfficeTab element -->
  <!-- <OfficeTab id="TabData"> -->
    <Label resid="residLabel4" />
    <Group id="Group1Id12">
      <Label resid="residLabel4" />
      <Icon>
        <bt:Image size="16" resid="icon1_32x32" />
        <bt:Image size="32" resid="icon1_32x32" />
        <bt:Image size="80" resid="icon1_32x32" />
      </Icon>
      <Tooltip resid="residToolTip" />
      <Control xsi:type="Button" id="Button1Id1">

        <!-- information about the control -->
      </Control>
      <!-- other controls, as needed -->
    </Group>
  </CustomTab>
</ExtensionPoint>
<ExtensionPoint xsi:type="ContextMenu">
  <OfficeMenu id="ContextMenuCell">
    <Control xsi:type="Menu" id="ContextMenu2">
            <!-- information about the control -->
    </Control>
    <!-- other controls, as needed -->
  </OfficeMenu>
</ExtensionPoint>
ЭлементElement ОписаниеDescription
CustomTabCustomTab
Обязательный, если требуется добавить пользовательскую вкладку в ленту (с помощью элемента PrimaryCommandSurface). Невозможно использовать элементы CustomTab и OfficeTab одновременно. Атрибут id является обязательным. Required if you want to add a custom tab to the ribbon (using PrimaryCommandSurface). If you use the CustomTab element, you can't use the OfficeTab element. The id attribute is required.
OfficeTabOfficeTab
Обязательный, если требуется расширить стандартную вкладку ленты Office (с помощью элемента PrimaryCommandSurface). Невозможно использовать элементы OfficeTab и CustomTab одновременно. Required if you want to extend a default Office ribbon tab (using PrimaryCommandSurface). If you use the OfficeTab element, you can't use the CustomTab element.
Дополнительные значения, которые можно использовать с атрибутом id, см. в разделе Значения для стандартных вкладок Office.For more tab values to use with the id attribute, see Tab values for default Office ribbon tabs.
OfficeMenuOfficeMenu
Обязательный при добавлении команд надстройки в контекстное меню по умолчанию (с помощью элемента ContextMenu). Для атрибута id необходимо задать следующее значение: Required if you're adding add-in commands to a default context menu (using ContextMenu). The id attribute must be set to:
ContextMenuText для Excel или Word. Отображает элемент в контекстном меню, когда пользователь щелкает выделенный текст правой кнопкой мыши.ContextMenuText for Excel or Word. Displays the item on the context menu when text is selected and then the user right-clicks on the selected text.
ContextMenuCell для Excel. Отображает элемент в контекстном меню, когда пользователь щелкает ячейку электронной таблицы правой кнопкой мыши. ContextMenuCell for Excel. Displays the item on the context menu when the user right-clicks on a cell on the spreadsheet.
GroupGroup
Группа точек расширения интерфейса пользователя на вкладке. В группе может быть до шести элементов управления. Атрибут id является обязательным. Это строка длиной до 125 символов. A group of user interface extension points on a tab. A group can have up to six controls. The id attribute is required. It's a string with a maximum of 125 characters.
LabelLabel
Обязательный. Метка группы. Для атрибута resid должно быть задано значение атрибута id, принадлежащего элементу String. String — это дочерний элемент ShortStrings, который в свою очередь является дочерним для элемента Resources. Required. The label of the group. The resid attribute must be set to the value of the id attribute of a String element. The String element is a child element of the ShortStrings element, which is a child element of the Resources element.
IconIcon
Обязательный. Определяет значок группы для использования на устройствах с малым форм-фактором или в случаях, когда отображается слишком много кнопок. Для атрибута resid должно быть задано значение атрибута id, принадлежащего элементу Image. Image — это дочерний элемент Images, который в свою очередь является дочерним для элемента Resources. Атрибут size определяет размер изображения в пикселях. Обязательными являются три размера изображения: 16, 32 и 80. Кроме того, поддерживаются пять необязательных размеров: 20, 24, 40, 48 и 64. Required. Specifies the group's icon to be used on small form factor devices, or when too many buttons are displayed. The resid attribute must be set to the value of the id attribute of an Image element. The Image element is a child element of the Images element, which is a child element of the Resources element. The size attribute gives the size, in pixels, of the image. Three image sizes are required: 16, 32, and 80. Five optional sizes are also supported: 20, 24, 40, 48, and 64.
TooltipTooltip
Необязательный параметр. Всплывающая подсказка группы. Для атрибута resid должно быть задано значение атрибута id, принадлежащего элементу String. String — это дочерний элемент LongStrings, который в свою очередь является дочерним для элемента Resources. Optional. The tooltip of the group. The resid attribute must be set to the value of the id attribute of a String element. The String element is a child element of the LongStrings element, which is a child element of the Resources element.
ControlControl
Для каждой группы требуется хотя бы один элемент управления. Элемент Control может иметь значение Button или Menu. Укажите Menu, чтобы задать раскрывающийся список элементов управления "Кнопка". В настоящий момент поддерживаются только кнопки и меню. Дополнительные сведения см. в разделах Элементы управления "Кнопка" и Элементы управления "Меню".Each group requires at least one control. A Control element can be either a Button or a Menu. Use Menu to specify a drop-down list of button controls. Currently, only buttons and menus are supported. See the Button controls and Menu controls sections for more information.
Примечание. Чтобы упростить устранение неполадок, рекомендуем добавлять элемент Control и соответствующие дочерние элементы Resources по одному.Note: To make troubleshooting easier, we recommend that you add a Control element and the related Resources child elements one at a time.

Элементы управления "Кнопка"Button controls

Когда пользователь нажимает кнопку, она выполняет одно действие. Она может выполнять функцию JavaScript или отображать область задач. В приведенном ниже примере показано, как определить две кнопки. Первая кнопка выполняет функцию JavaScript без отображения пользовательского интерфейса, а вторая отображает область задач. В элементе Control:A button performs a single action when the user selects it. It can either execute a JavaScript function or show a task pane. The following example shows how to define two buttons. The first button runs a JavaScript function without showing a UI, and the second button shows a task pane. In the Control element:

  • атрибут type является обязательным и должен иметь значение Button;The type attribute is required, and must be set to Button.

  • атрибут id элемента Control — это строка длиной до 125 символов.The id attribute of the Control element is a string with a maximum of 125 characters.

<!-- Define a control that calls a JavaScript function. -->
<Control xsi:type="Button" id="Button1Id1">
  <Label resid="residLabel" />
  <Tooltip resid="residToolTip" />
  <Supertip>
    <Title resid="residLabel" />
    <Description resid="residToolTip" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="icon1_32x32" />
    <bt:Image size="32" resid="icon1_32x32" />
    <bt:Image size="80" resid="icon1_32x32" />
  </Icon>
  <Action xsi:type="ExecuteFunction">
    <FunctionName>getData</FunctionName>
  </Action>
</Control>

<!-- Define a control that shows a task pane. -->
<Control xsi:type="Button" id="Button2Id1">
  <Label resid="residLabel2" />
  <Tooltip resid="residToolTip" />
  <Supertip>
    <Title resid="residLabel" />
    <Description resid="residToolTip" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="icon2_32x32" />
    <bt:Image size="32" resid="icon2_32x32" />
    <bt:Image size="80" resid="icon2_32x32" />
  </Icon>
  <Action xsi:type="ShowTaskpane">
    <SourceLocation resid="residUnitConverterUrl" />
  </Action>
</Control>
ЭлементыElements ОписаниеDescription
LabelLabel
Обязательный. Текст для кнопки. Для атрибута resid должно быть задано значение атрибута id, принадлежащего элементу String. String — это дочерний элемент ShortStrings, который в свою очередь является дочерним для элемента Resources. Required. The text for the button. The resid attribute must be set to the value of the id attribute of a String element. The String element is a child element of the ShortStrings element, which is a child element of the Resources element.
TooltipTooltip
Необязательный параметр. Всплывающая подсказка для кнопки. Для атрибута resid должно быть задано значение атрибута id, принадлежащего элементу String. String — это дочерний элемент LongStrings, который в свою очередь является дочерним для элемента Resources. Optional. The tooltip for the button. The resid attribute must be set to the value of the id attribute of a String element. The String element is a child element of the LongStrings element, which is a child element of the Resources element.
SupertipSupertip
Обязательный элемент. Суперподсказка для кнопки, определяемая указанными ниже элементами. Required. The supertip for this button, which is defined by the following:
TitleTitle
Обязательный. Текст суперподсказки. Для атрибута resid должно быть задано значение атрибута id, принадлежащего элементу String. String — это дочерний элемент ShortStrings, который в свою очередь является дочерним для элемента Resources. Required. The text for the supertip. The resid attribute must be set to the value of the id attribute of a String element. The String element is a child element of the ShortStrings element, which is a child element of the Resources element.
ОписаниеDescription
Обязательный. Описание суперподсказки. Для атрибута resid должно быть задано значение атрибута id, принадлежащего элементу String. String — это дочерний элемент LongStrings, который в свою очередь является дочерним для элемента Resources. Required. The description for the supertip. The resid attribute must be set to the value of the id attribute of a String element. The String element is a child element of the LongStrings element, which is a child element of the Resources element.
IconIcon
Обязательный. Содержит элементы Image для кнопки. Файлы изображений должны быть в формате PNG. Required. Contains the Image elements for the button. Image files must be .png format.
ImageImage
Определяет изображение для кнопки. Для атрибута resid должно быть задано значение атрибута id, принадлежащего элементу Image. Image — это дочерний элемент Images, который в свою очередь является дочерним для элемента Resources. Атрибут size определяет размер изображения в пикселях. Обязательными являются три размера изображения: 16, 32 и 80. Кроме того, поддерживаются пять необязательных размеров: 20, 24, 40, 48 и 64. Defines an image to display on the button. The resid attribute must be set to the value of the id attribute of an Image element. The Image element is a child element of the Images element, which is a child element of the Resources element. The size attribute indicates the size, in pixels, of the image. Three image sizes are required: 16, 32, and 80. Five optional sizes are also supported: 20, 24, 40, 48, and 64.
ДействиеAction
Обязательный. Указывает действие, которое необходимо выполнить, когда пользователь нажимает кнопку. Для этого атрибута xsi:type можно указать следующие значения: Required. Specifies the action to perform when the user selects the button. You can specify one of the following values for the xsi:type attribute:
ExecuteFunction. Вызывает функцию JavaScript, расположенную в файле, на который ссылается элемент FunctionFile. ExecuteFunction не отображает пользовательский интерфейс. Дочерний элемент FunctionName задает имя выполняемой функции.ExecuteFunction, which runs a JavaScript function located in the file referenced by FunctionFile. ExecuteFunction does not display a UI. The FunctionName child element specifies the name of the function to execute.
ShowTaskPane. Отображает надстройку области задач. Дочерний элемент SourceLocation задает расположение исходного файла отображаемой надстройки области задач. Для атрибута resid должно быть задано значение атрибута id элемента Url в элементе Urls, включенном в элемент Resources. ShowTaskPane, which shows a task pane add-in. The SourceLocation child element specifies the source file location of the task pane add-in to display. The resid attribute must be set to the value of the id attribute of a Url element in the Urls element in the Resources element.

Элемент управления Меню можно использовать с элементом PrimaryCommandSurface или ContextMenu. Он определяет следующее:A Menu control can be used with either PrimaryCommandSurface or ContextMenu, and defines:

  • элемент меню корневого уровня;A root-level menu item.

  • список элементов подменю.A list of submenu items.

При использовании совместно с элементом PrimaryCommandSurface, корневой элемент меню отображается в виде кнопки на ленте. При выборе кнопки отображается подменю в виде раскрывающегося списка. При использовании совместно с элементом ContextMenu, элемент меню с подменю вставляется в контекстное меню. В обоих случаях индивидуальные элементы подменю могут выполнять функцию JavaScript или отображать область задач. В настоящее время поддерживается только один уровень подменю.When used with PrimaryCommandSurface, the root menu item displays as a button on the ribbon. When the button is selected, the submenu displays as a drop-down list. When used with ContextMenu, a menu item with a submenu is inserted on the context menu. In both cases, individual submenu items can either execute a JavaScript function or show a task pane. Only one level of submenus is supported at this time.

В приведенном ниже примере показано, как определить элемент меню с двумя элементами подменю. Первый элемент подменю показывает область задач, а второй запускает функцию JavaScript. В элементе Control:The following example shows how to define a menu item with two submenu items. The first submenu item shows a task pane, and the second submenu item runs a JavaScript function. In the Control element:

  • атрибут xsi:type является обязательным и должен иметь значение Menu;The xsi:type attribute is required, and must be set to Menu.

  • атрибут id — это строка длиной до 125 символов.The id attribute is a string with a maximum of 125 characters.


<Control xsi:type="Menu" id="TestMenu2">
  <Label resid="residLabel3" />
  <Tooltip resid="residToolTip" />
  <Supertip>
    <Title resid="residLabel" />
    <Description resid="residToolTip" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="icon1_32x32" />
    <bt:Image size="32" resid="icon1_32x32" />
    <bt:Image size="80" resid="icon1_32x32" />
  </Icon>
  <Items>
    <Item id="showGallery2">
      <Label resid="residLabel3"/>
      <Supertip>
        <Title resid="residLabel" />
        <Description resid="residToolTip" />
      </Supertip>
      <Icon>
        <bt:Image size="16" resid="icon1_32x32" />
        <bt:Image size="32" resid="icon1_32x32" />
        <bt:Image size="80" resid="icon1_32x32" />
      </Icon>
      <Action xsi:type="ShowTaskpane">
        <TaskpaneId>MyTaskPaneID1</TaskpaneId>
        <SourceLocation resid="residUnitConverterUrl" />
      </Action>
    </Item>
    <Item id="showGallery3">
      <Label resid="residLabel5"/>
      <Supertip>
        <Title resid="residLabel" />
        <Description resid="residToolTip" />
      </Supertip>
      <Icon>
        <bt:Image size="16" resid="icon4_32x32" />
        <bt:Image size="32" resid="icon4_32x32" />
        <bt:Image size="80" resid="icon4_32x32" />
      </Icon>
      <Action xsi:type="ExecuteFunction">
        <FunctionName>getButton</FunctionName>
      </Action>
    </Item>
  </Items>
</Control>
ЭлементыElements ОписаниеDescription
LabelLabel
Обязательный. Текст корневого элемента меню. Для атрибута resid должно быть задано значение атрибута id, принадлежащего элементу String. String — это дочерний элемент ShortStrings, который в свою очередь является дочерним для элемента Resources. Required. The text of the root menu item. The resid attribute must be set to the value of the id attribute of a String element. The String element is a child element of the ShortStrings element, which is a child element of the Resources element.
TooltipTooltip
Необязательный параметр. Всплывающая подсказка для меню. Для атрибута resid должно быть задано значение атрибута id, принадлежащего элементу String. String — это дочерний элемент LongStrings, который в свою очередь является дочерним для элемента Resources. Optional. The tooltip for the menu. The resid attribute must be set to the value of the id attribute of a String element. The String element is a child element of the LongStrings element, which is a child element of the Resources element.
SuperTipSuperTip
Обязательный элемент. Суперподсказка для меню, определяемая указанными ниже элементами. Required. The supertip for the menu, which is defined by the following:
TitleTitle
Обязательный. Текст суперподсказки. Для атрибута resid должно быть задано значение атрибута id, принадлежащего элементу String. String — это дочерний элемент ShortStrings, который в свою очередь является дочерним для элемента Resources. Required. The text of the supertip. The resid attribute must be set to the value of the id attribute of a String element. The String element is a child element of the ShortStrings element, which is a child element of the Resources element.
ОписаниеDescription
Обязательный. Описание суперподсказки. Для атрибута resid должно быть задано значение атрибута id, принадлежащего элементу String. String — это дочерний элемент LongStrings, который в свою очередь является дочерним для элемента Resources. Required. The description for the supertip. The resid attribute must be set to the value of the id attribute of a String element. The String element is a child element of the LongStrings element, which is a child element of the Resources element.
IconIcon
Обязательный. Содержит элементы Image для меню. Файлы изображений должны быть в формате PNG. Required. Contains the Image elements for the menu. Image files must be .png format.
ImageImage
Изображение для меню. Для атрибута resid должно быть задано значение атрибута id, принадлежащего элементу Image. Image — это дочерний элемент Images, который в свою очередь является дочерним для элемента Resources. Атрибут size определяет размер изображения в пикселях. Обязательными являются три размера изображения в пикселях: 16, 32 и 80. Кроме того, поддерживаются пять необязательных размеров в пикселях: 20, 24, 40, 48 и 64. An image for the menu. The resid attribute must be set to the value of the id attribute of an Image element. The Image element is a child element of the Images element, which is a child element of the Resources element. The size attribute indicates the size in pixels of the image. Three image sizes, in pixels, are required: 16, 32, and 80. Five optional sizes, in pixels, are also supported: 20, 24, 40, 48, and 64.
ItemsItems
Обязательный. Содержит элементы Item для каждого элемента подменю. Каждый элемент Item содержит те же дочерние элементы, что и Элементы управления ''Кнопка''. Required. Contains the Item elements for each submenu item. Each Item element contains the same child elements as Button controls.

Этап 7. Добавление элемента ResourcesStep 7: Add the Resources element

Элемент Resources содержит ресурсы, используемые различными дочерними элементами элемента VersionOverrides. Ресурсы включают значки, строки и URL-адреса. Элемент манифеста может использовать ресурс, ссылаясь на его id. Использование id помогает упорядочить манифест, особенно если для разных языковых стандартов используются разные версии ресурса. id может содержать до 32 знаков.The Resources element contains resources used by the different child elements of the VersionOverrides element. Resources include icons, strings, and URLs. An element in the manifest can use a resource by referencing the id of the resource. Using the id helps organize the manifest, especially when there are different versions of the resource for different locales. An id has a maximum of 32 characters.

Ниже приведен пример использования элемента Resources. Каждый ресурс может иметь один или несколько дочерних элементов Override, позволяющих указать другой ресурс для определенного языкового стандарта.The following shows an example of how to use the Resources element. Each resource can have one or more Override child elements to define a different resource for a specific locale.

<Resources>
  <bt:Images>
    <bt:Image id="icon1_16x16" DefaultValue="https://www.contoso.com/Images/icon_default.png">
      <bt:Override Locale="ja-jp" Value="https://www.contoso.com/Images/ja-jp16-icon_default.png" />
    </bt:Image>
    <bt:Image id="icon1_32x32" DefaultValue="https://www.contoso.com/Images/icon_default.png">
      <bt:Override Locale="ja-jp" Value="https://www.contoso.com/Images/ja-jp32-icon_default.png" />
    </bt:Image>
    <bt:Image id="icon1_80x80" DefaultValue="https://www.contoso.com/Images/icon_default.png">
      <bt:Override Locale="ja-jp" Value="https://www.contoso.com/Images/ja-jp80-icon_default.png" />
    </bt:Image>
  </bt:Images>
  <bt:Urls>
    <bt:Url id="residDesktopFuncUrl" DefaultValue="https://www.contoso.com/Pages/Home.aspx">
      <bt:Override Locale="ja-jp" Value="https://www.contoso.com/Pages/Home.aspx" />
    </bt:Url>
  </bt:Urls>
  <bt:ShortStrings>
    <bt:String id="residLabel" DefaultValue="GetData">
      <bt:Override Locale="ja-jp" Value="JA-JP-GetData" />
    </bt:String>
  </bt:ShortStrings>
  <bt:LongStrings>
    <bt:String id="residToolTip" DefaultValue="Get data for your document.">
      <bt:Override Locale="ja-jp" Value="JA-JP - Get data for your document." />
    </bt:String>
  </bt:LongStrings>
</Resources>
РесурсResource ОписаниеDescription
Images/ ImageImages/ Image
Предоставляет URL-адрес файла изображения по протоколу HTTPS. Каждое изображение должно быть определено в трех обязательных размерах:Provides the HTTPS URL to an image file. Each image must define the three required image sizes:
16×1616×16
32×3232×32
80×8080×80
Кроме того, поддерживаются следующие необязательные размеры:The following image sizes are also supported, but not required:
20×2020×20
24×2424×24
40×4040×40
48×4848×48
64×6464×64
Urls/ UrlUrls/ Url
Предоставляет URL-адрес с префиксом HTTPS. URL-адрес может включать до 2048 символов.Provides an HTTPS URL location. A URL can be a maximum of 2048 characters.
ShortStrings/ StringShortStrings/ String
Текст для элементов Label и Title. Каждая строка содержит не более 125 символов. The text for Label and Title elements. Each String contains a maximum of 125 characters.
LongStrings/ StringLongStrings/ String
Текст для элементов Tooltip и Description. Каждый элемент String содержит не более 250 символов.The text for Tooltip and Description elements. Each String contains a maximum of 250 characters.

Примечание

Для всех URL-адресов в элементах Image и Url необходимо использовать протокол SSL.You must use Secure Sockets Layer (SSL) for all URLs in the Image and Url elements.

Значения для стандартных вкладок ленты OfficeTab values for default Office ribbon tabs

В Excel и Word вы можете добавить команды надстройки на ленту с помощью стандартных вкладок пользовательского интерфейса Office. В приведенной ниже таблице перечислены значения, которые можно использовать для атрибута id элемента OfficeTab. Значения вкладок указываются с учетом регистра.In Excel and Word, you can add your add-in commands to the ribbon by using the default Office UI tabs. The following table lists the values that you can use for the id attribute of the OfficeTab element. The tab values are case sensitive.

Ведущее приложение OfficeOffice host application Значения вкладокTab values
ExcelExcel
TabHome TabInsert TabPageLayoutExcel TabFormulas TabData TabReview TabView TabDeveloper TabAddIns TabPrintPreview TabBackgroundRemovalTabHome TabInsert TabPageLayoutExcel TabFormulas TabData TabReview TabView TabDeveloper TabAddIns TabPrintPreview TabBackgroundRemoval
WordWord
TabHome TabInsert TabWordDesign TabPageLayoutWord TabReferences TabMailings TabReviewWord TabView TabDeveloper TabAddIns TabBlogPost TabBlogInsert TabPrintPreview TabOutlining TabConflicts TabBackgroundRemoval TabBroadcastPresentationTabHome TabInsert TabWordDesign TabPageLayoutWord TabReferences TabMailings TabReviewWord TabView TabDeveloper TabAddIns TabBlogPost TabBlogInsert TabPrintPreview TabOutlining TabConflicts TabBackgroundRemoval TabBroadcastPresentation
PowerPointPowerPoint
TabHome TabInsert TabDesign TabTransitions TabAnimations TabSlideShow TabReview TabView TabDeveloper TabAddIns TabPrintPreview TabMerge TabGrayscale TabBlackAndWhite TabBroadcastPresentation TabSlideMaster TabHandoutMaster TabNotesMaster TabBackgroundRemoval TabSlideMasterHomeTabHome TabInsert TabDesign TabTransitions TabAnimations TabSlideShow TabReview TabView TabDeveloper TabAddIns TabPrintPreview TabMerge TabGrayscale TabBlackAndWhite TabBroadcastPresentation TabSlideMaster TabHandoutMaster TabNotesMaster TabBackgroundRemoval TabSlideMasterHome

См. такжеSee also