Ribbon XMLRibbon XML

Элемент Лента (XML) позволяет настраивать ленту с помощью XML.The Ribbon (XML) item enables you to customize a ribbon by using XML. Используйте элемент Лента (XML), если требуется настроить ленту способом, который не поддерживается элементом Лента (визуальный конструктор).Use the Ribbon (XML) item if you want to customize the ribbon in a way that is not supported by the Ribbon (Visual Designer) item. Сравнение того, что можно делать с каждым элементом, см. в разделе лента Обзор ленты.For a comparison of what you can do with each item, see Ribbon overview.

Применимо к: Сведения в этом разделе относятся к - проектам уровня документа и к добавлению VSTO - в проекты для следующих приложений: Excel; InfoPath 2013 и InfoPath 2010; Невозможно Приложения Проектом Исправления Словам.Applies to: The information in this topic applies to document-level projects and VSTO Add-in projects for the following applications: Excel; InfoPath 2013 and InfoPath 2010; Outlook; PowerPoint; Project; Visio; Word. Дополнительные сведения см. в разделе доступность функций по типам приложений Office и проектов.For more information, see Features available by Office application and project type.

Добавление элемента ленты (XML) в проектAdd a Ribbon (XML) item to a project

Элемент Лента (XML) можно добавить в любой проект Office из диалогового окна Добавить новый элемент .You can add a Ribbon (XML) item to any Office project from the Add New Item dialog box. Visual Studio автоматически добавляет в проект следующие файлы.Visual Studio automatically adds the following files to your project:

  • XML-файл ленты.A Ribbon XML file. Этот файл определяет пользовательский интерфейс ленты.This file defines the Ribbon user interface (UI). Данный файл можно использовать для добавления элементов пользовательского интерфейса — вкладок, групп и элементов управления.Use this file to add UI elements such as tabs, groups, and controls. Дополнительные сведения см. Далее в разделе Справочник по XML-файлу ленты .For details, see Ribbon XML file reference later in this topic.

  • Файл кода ленты.A Ribbon code file. Этот файл содержит класс ленты.This file contains the Ribbon class. Класс имеет имя, указанное для элемента Лента (XML) в диалоговом окне Добавить новый элемент .This class has the name that you specified for the Ribbon (XML) item in the Add New Item dialog box. Microsoft Office приложения используют экземпляр этого класса для загрузки настраиваемой ленты.Microsoft Office applications use an instance of this class to load the custom ribbon. Дополнительные сведения см. в разделе ссылка на класс ленты далее в этой статье.For details, see Ribbon class reference later in this topic.

    По умолчанию эти файлы добавляют пользовательскую группу к вкладке надстройки на ленте.By default, these files add a custom group to the Add-Ins tab in the ribbon.

Отображение настраиваемой ленты в приложении Microsoft OfficeDisplay the custom ribbon in a Microsoft Office application

После добавления элемента ленты (XML) в проект необходимо добавить код в класс ThisAddIn, ThisWorkbook или ThisDocument , который переопределяет CreateRibbonExtensibilityObject метод и возвращает класс XML ленты в приложение Office.After you add a Ribbon (XML) item to your project, you must add code to the ThisAddin, ThisWorkbook, or ThisDocument class that overrides the CreateRibbonExtensibilityObject method and returns the Ribbon XML class to the Office application.

В следующем примере кода переопределяется метод CreateRibbonExtensibilityObject и возвращается XML-класс ленты с именем MyRibbon.The following code example overrides the CreateRibbonExtensibilityObject method and returns a Ribbon XML class named MyRibbon.

protected override Microsoft.Office.Core.IRibbonExtensibility CreateRibbonExtensibilityObject()
{
    return new MyRibbon();
}
Protected Overrides Function CreateRibbonExtensibilityObject() As  _
Microsoft.Office.Core.IRibbonExtensibility
    Return New MyRibbon()
End Function

Определение поведения настраиваемой лентыDefine the behavior of the custom ribbon

Вы можете реагировать на действия пользователя, такие как нажатие кнопки на ленте, путем создания методов обратного вызова.You can respond to user actions, such as clicking a button on the ribbon, by creating callback methods. Методы обратного вызова похожи на события в элементах управления Windows Forms, но они идентифицируются атрибутом в XML-коде элемента пользовательского интерфейса.Callback methods resemble events in Windows Forms controls, but they are identified by an attribute in the XML of the UI element. Вы записываете методы в классе ленты, а элемент управления вызывает метод, который имеет то же имя, что и значение атрибута.You write methods in the Ribbon class, and a control calls the method that has the same name as the attribute value. Например, можно создать метод обратного вызова, который вызывается, когда пользователь нажимает кнопку на ленте.For example, you can create a callback method that is called when a user clicks a button on the ribbon. Для создания метода обратного вызова необходимо выполнить два действия.Two steps are required to create a callback method:

  • Назначьте атрибут элементу управления в XML-файле ленты, который идентифицирует метод обратного вызова в коде.Assign an attribute to a control in the Ribbon XML file that identifies a callback method in your code.

  • Определите метод обратного вызова в классе ленты.Define the callback method in the Ribbon class.

Примечание

Для Outlook необходимо будет выполнить еще одно действие.Outlook requires an additional step. Дополнительные сведения см. в разделе Настройка ленты для Outlook.For more information, see Customize a ribbon for Outlook.

Пошаговое руководство, в котором показано, как автоматизировать приложение на ленте, см. в разделе Пошаговое руководство. Создание настраиваемой вкладки с помощью XML-ленты.For a walkthrough that demonstrates how to automate an application from the ribbon, see Walkthrough: Create a custom tab by using Ribbon XML.

Назначение методов обратного вызова элементам управленияAssign callback methods to controls

Для назначения метода обратного вызова элементу управления в XML-файле ленты добавьте атрибут, который указывает тип метода обратного вызова и имя данного метода.To assign a callback method to a control in the Ribbon XML file, add an attribute that specifies the type of the callback method and the name of the method. Например, следующий элемент определяет выключатель, который имеет метод обратного вызова onAction с именем OnToggleButton1.For example, the following element defines a toggle button that has an onAction callback method named OnToggleButton1.

<toggleButton id="toggleButton1" onAction="OnToggleButton1" />

onAction вызывается, когда пользователь выполняет основную задачу, связанную с конкретным элементом управления.onAction is called when the user performs the main task associated with a particular control. Например, метод обратного вызова onAction выключателя вызывается, когда пользователь нажимает кнопку.For example, the onAction callback method of a toggle button is called when the user clicks the button.

Метод, указываемый в атрибуте, может иметь любое имя.The method that you specify in the attribute can have any name. Тем не менее данное имя должно соответствовать имени метода, который определяется в файле кода ленты.However, it must match the name of the method that you define in the Ribbon code file.

Элементам управления ленты можно назначать методы обратного вызова различного типа.There are many different types of callback methods that you can assign to Ribbon controls. Полный список методов обратного вызова, доступных для каждого элемента управления, см. в технической статье Настройка пользовательского интерфейса ленты Office (2007) для разработчиков (часть 3 из 3).For a complete list of the callback methods available for each control, see the technical article Customize the Office (2007) Ribbon user interface for developers (Part 3 of 3).

Определение методов обратного вызоваDefine callback methods

Определите методы обратного вызова в классе ленты в файле кода ленты.Define your callback methods in the Ribbon class in the Ribbon code file. Метод обратного вызова должен удовлетворять ряду требований.A callback method has several requirements:

  • Он должен быть объявлен как открытый.It must be declared as public.

  • Его имя должно соответствовать имени метода обратного вызова, которое назначено элементу управления в XML-файле ленты.Its name must match the name of a callback method that you assigned to a control in the Ribbon XML file.

  • Его сигнатура должна соответствовать сигнатуре метода обратного вызова, доступного для связанного элемента управления ленты.Its signature must match the signature of a type of callback method that is available for the associated Ribbon control.

    Полный список сигнатур методов обратного вызова для элементов управления ленты см. в технической статье Настройка пользовательского интерфейса ленты Office (2007) для разработчиков (часть 3 из 3).For a complete list of the callback method signatures for Ribbon controls, see the technical article Customize the Office (2007) Ribbon user interface for developers (Part 3 of 3). Visual Studio не поддерживает IntelliSense для методов обратного вызова, которые создаются в файле кода ленты.Visual Studio does not provide IntelliSense support for callback methods that you create in the Ribbon code file. Если создать метод обратного вызова, который не соответствует допустимой сигнатуре, код будет скомпилирован, но, когда пользователь щелкнет элемент управления, ничего не произойдет.If you create a callback method that does not match a valid signature, the code will compile, but nothing will occur when the user clicks the control.

    Все методы обратного вызова имеют параметр IRibbonControl , который представляет элемент управления, вызвавший метод.All callback methods have a IRibbonControl parameter that represents the control that called the method. Этот параметр позволяет повторно использовать один и тот же метод обратного вызова для нескольких элементов управления.You can use this parameter to reuse the same callback method for multiple controls. В следующем примере кода демонстрируется метод обратного вызова onAction , который выполняет различные задачи в зависимости от того, какой элемент управления щелкает пользователь.The following code example demonstrates an onAction callback method that performs different tasks depending on which control the user clicks.

    public void OnActionCallback(Office.IRibbonControl control, bool isPressed)
    {
        if (control.Id == "checkBox1")
        {
            MessageBox.Show("You clicked " + control.Id);
        }
        else
        {
            MessageBox.Show("You clicked a different control.");
        }
    }
    
    Public Sub OnActionCallback(ByVal control As Office.IRibbonControl, _
        ByVal isPressed As Boolean)
    
        If (control.Id = "checkBox1") Then
            MessageBox.Show("You clicked " + control.Id)
        Else
            MessageBox.Show("You clicked a different control.")
        End If
    
    End Sub
    

Справочник по XML-файлу лентыRibbon XML file reference

Вы можете определить пользовательскую ленту, добавив элементы и атрибуты в XML-файл ленты.You can define your custom ribbon by adding elements and attributes to the Ribbon XML file. По умолчанию XML-файл ленты содержит следующий XML-код.By default, the Ribbon XML file contains the following XML.

<?xml version="1.0" encoding="UTF-8"?>
<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui" onLoad="OnLoad">
  <ribbon>
    <tabs>
      <tab idMso="TabAddIns">
        <group id="MyGroup"
               label="My Group">
        </group>
      </tab>
    </tabs>
  </ribbon>
</customUI>

В следующей таблице указаны элементы по умолчанию в XML-файле ленты.The following table describes the default elements in the Ribbon XML file.

ЭлементElement ОписаниеDescription
customUIcustomUI Представляет пользовательскую ленту в проекте надстройки VSTO.Represents the custom ribbon in the VSTO Add-in project.
лентеribbon Представляет ленту.Represents the ribbon.
соответствующуюtabs Представляет набор вкладок на ленте.Represents a set of Ribbon tabs.
вкладкеtab Представляет одну вкладку на ленте.Represents a single Ribbon tab.
groupgroup Представляет группу элементов управления на вкладке ленты.Represents a group of controls on the Ribbon tab.

Эти элементы имеют атрибуты, определяющие внешний вид и поведение настраиваемой ленты.These elements have attributes that specify the appearance and behavior of the custom ribbon. В следующей таблице указаны атрибуты по умолчанию в XML-файле ленты.The following table describes the default attributes in the Ribbon XML file.

attributeAttribute Родительский элементParent element ОписаниеDescription
onLoadonLoad customUIcustomUI Определяет метод, который вызывается, когда приложение загружает ленту.Identifies a method that is called when the application loads the ribbon.
idMsoidMso вкладкеtab Определяет встроенную вкладку, отображаемую на ленте.Identifies a built-in tab to display in the ribbon.
idid groupgroup Идентифицирует группу.Identifies the group.
labellabel groupgroup Указывает текст, отображаемый в группе.Specifies the text that appears on the group.

Элементы и атрибуты по умолчанию в XML-файле ленты представляют собой небольшое подмножество доступных элементов и атрибутов.The default elements and attributes in the Ribbon XML file are a small subset of the elements and attributes that are available. Полный список доступных элементов и атрибутов см. в технической статье Настройка пользовательского интерфейса ленты Office (2007) для разработчиков (часть 2 из 3).For a complete list of the available elements and attributes, see the technical article Customize the Office (2007) Ribbon user interface for developers (Part 2 of 3).

Справочник по классам лентыRibbon class reference

Visual Studio создает класс ленты в файле кода ленты.Visual Studio generates the Ribbon class in the Ribbon code file. Добавьте методы обратного вызова для элементов управления на ленте в этот класс.Add the callback methods for controls on the ribbon to this class. Этот класс реализует интерфейс IRibbonExtensibility .This class implements the IRibbonExtensibility interface.

В следующей таблице указаны методы по умолчанию в этом классе.The following table describes the default methods in this class.

МетодMethod ОписаниеDescription
GetCustomUI Возвращает содержимое XML-файла ленты.Returns the contents of the Ribbon XML file. Microsoft Office приложения вызывают этот метод для получения XML-строки, определяющей пользовательский интерфейс настраиваемой ленты.Microsoft Office applications call this method to obtain an XML string that defines the user interface of your custom ribbon. Этот метод реализует метод GetCustomUI .This method implements the GetCustomUI method. Примечание. GetCustomUI должен быть реализован только для возврата содержимого XML-файла ленты; его не следует использовать для инициализации надстройки VSTO. Note: GetCustomUI should be implemented only to return the contents of the Ribbon XML file; it should not be used to initialize your VSTO Add-in. В частности, не пытайтесь отображать диалоговые или прочие окна в своей реализации GetCustomUI .In particular, you should not try to display dialog boxes or other windows in your GetCustomUI implementation. В противном случае пользовательская лента может работать неправильно.Otherwise, the custom ribbon might not behave correctly. Если необходимо запускать код, который инициализирует надстройку VSTO, добавьте этот код в обработчик событий ThisAddIn_Startup .If you have to run code that initializes your VSTO Add-in, add the code to the ThisAddIn_Startup event handler.
OnLoad Назначает параметр IRibbonControl полю Ribbon .Assigns the IRibbonControl parameter to the Ribbon field. Microsoft Office приложения вызывают этот метод при загрузке пользовательской ленты.Microsoft Office applications call this method when they load the custom ribbon. Это поле можно использовать для динамического обновления настраиваемой ленты.You can use this field to dynamically update the custom ribbon. Дополнительные сведения см. в технической статье Настройка пользовательского интерфейса ленты Office (2007) для разработчиков (часть 1 из 3).For more information, see the technical article Customize the Office (2007) Ribbon user interface for developers (Part 1 of 3).
GetResourceText Вызывается методом GetCustomUI для получения содержимого XML-файла ленты.Called by the GetCustomUI method to obtain the contents of the Ribbon XML file.

См. также статьюSee also