功能区 XML

通过“功能区（XML）”项，可以使用 XML 自定义功能区。 如果要以功能区（可视化设计器）项不支持的方式自定义功能区，请使用功能区 （XML） 项。 有关每个项目可执行操作的比较，请参阅功能区概述。

适用于： 本主题中的信息适用于以下应用程序的文档级项目和 VSTO 外接程序项目：Excel、InfoPath 2013 和 InfoPath 2010、Outlook、PowerPoint、Project、Visio、Word。 有关详细信息，请参阅 Office 应用程序和项目类型提供的功能。

向项目添加功能区 （XML） 项

可以从“添加新项”对话框将功能区（XML）项添加到任何 Office 项目。 Visual Studio 会自动将以下文件添加到项目中：

• 功能区 XML 文件。 此文件定义功能区用户界面（UI）。 使用此文件可添加 UI 元素，如选项卡、组和控件。 有关详细信息，请参阅本主题后面的 Ribbon XML 文件参考。

• 功能区代码文件。 此文件包含 Ribbon 类。 此类具有您在“添加新项”对话框中为Ribbon（XML）项指定的名称。 Microsoft Office 应用程序使用此类的实例来加载自定义功能区。 有关详细信息，请参阅本主题后面的Ribbon 类参考。

  默认情况下，这些文件将自定义组添加到功能区中的 “加载项 ”选项卡。

在 Microsoft Office 应用程序中显示自定义功能区

向项目中添加功能区（XML）项后，必须向ThisAddin、ThisWorkbook或ThisDocument类中添加代码，该代码会重写CreateRibbonExtensibilityObject方法，并将该功能区 XML 类返回给 Office 应用程序。

下面的代码示例重写了CreateRibbonExtensibilityObject方法，并返回一个名为 MyRibbon 的 Ribbon XML 类。

protected override Microsoft.Office.Core.IRibbonExtensibility CreateRibbonExtensibilityObject()
{
    return new MyRibbon();
}

Protected Overrides Function CreateRibbonExtensibilityObject() As  _
Microsoft.Office.Core.IRibbonExtensibility
    Return New MyRibbon()
End Function

定义自定义功能区的行为

可以通过创建 回调方法 来响应用户操作，例如单击功能区上的按钮。 回调方法类似于 Windows 窗体控件中的事件，但它们由 UI 元素的 XML 中的属性标识。 在 Ribbon 类中编写方法，控件调用与属性值同名的方法。 例如，可以创建在用户单击功能区上的按钮时调用的回调方法。 创建回调方法需要执行两个步骤：

• 将一个属性分配给功能区 XML 文件中的控件，以标识代码中的回调方法。

• 在 Ribbon 类中定义回调方法。

有关演示如何从功能区自动执行应用程序的演练，请参阅 演练：使用功能区 XML 创建自定义选项卡。

将回调方法分配给控件

若要将回调方法分配给功能区 XML 文件中的控件，请添加一个属性，该属性指定回调方法的类型和方法的名称。 例如，以下元素定义名为 onAction 回调方法 OnToggleButton1的切换按钮。

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

当用户执行与特定控件关联的主任务时，将调用 onAction。 例如，当用户单击该按钮时，将调用切换按钮的 onAction 回调方法。

在特性中指定的方法可以具有任何名称。 但是，它必须与在功能区代码文件中定义的方法的名称匹配。

可以向功能区控件分配许多不同类型的回调方法。 有关可用于每个控件的回调方法的完整列表，请参阅面向开发人员的 Office（2007） 功能区用户界面的技术文章（第 3 部分（共 3 部分）。

定义回调方法

在功能区代码文件中，定义功能区类中的回调方法。 回调方法有几个要求：

• 它必须声明为公共。

• 其名称必须与分配给 Ribbon XML 文件中控件回调函数的名称匹配。

• 其签名必须与可用于关联功能区控件的回调方法类型的签名相匹配。

  有关功能区控件回调方法签名完整列表的详细信息，请参阅技术文章 “Office（2007）功能区用户界面的定制指南：面向开发人员（第 3 部分）”。 Visual Studio 不提供对在功能区代码文件中创建的回调方法的 IntelliSense 支持。 如果创建与有效签名不匹配的回调方法，代码将编译，但在用户单击该控件时不会发生任何作。

  所有回调方法都有一个 IRibbonControl 参数，该参数表示调用该方法的控件。 可以使用此参数对多个控件重复使用相同的回调方法。 下面的代码示例演示了 一个 onAction 回调方法，该方法根据用户单击的控件执行不同的任务。

  • C#
  • VB

  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.");
      }
  }
  

功能区 XML 文件参考

可以通过向功能区 XML 文件添加元素和属性来定义自定义功能区。 默认情况下，功能区 XML 文件包含以下 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 文件中的默认元素。

这些元素具有用于指定自定义功能区外观和行为的属性。 下表描述了功能区 XML 文件中的默认属性。

功能区 XML 文件中的默认元素和属性是可用的元素和属性的一小部分。 有关可用元素和属性的完整列表，请参阅面向 开发人员的 Office（2007） 功能区用户界面（第 2 部分 3）的技术文章。

Ribbon类参考

Visual Studio 在功能区代码文件中生成功能区类。 将功能区控件的回调方法添加到这个类中。 此类实现 IRibbonExtensibility 接口。

下表描述了此类中的默认方法。

相关内容

• 功能区概述
• 教程：使用功能区 XML 创建自定义选项卡
• Office UI 自定义