功能区 XML

项目
09/10/2008

更新：2007 年 11 月

适用对象
本主题中的信息仅适用于指定的 Visual Studio Tools for Office 项目和 Microsoft Office 版本。项目类型文档级项目应用程序级项目 Microsoft Office 版本 Excel 2007 Word 2007 Outlook 2007 PowerPoint 2007 有关更多信息，请参见按应用程序和项目类型提供的功能。

本主题中的信息仅适用于指定的 Visual Studio Tools for Office 项目和 Microsoft Office 版本。

项目类型

文档级项目
应用程序级项目

Microsoft Office 版本

Excel 2007
Word 2007
Outlook 2007
PowerPoint 2007

有关更多信息，请参见按应用程序和项目类型提供的功能。

功能区 (XML) 项允许使用 XML 来自定义功能区。如果您希望通过“功能区(可视化设计器)”项不支持的方式来自定义功能区，则可以使用“功能区(XML)”项。有关使用每一种项可执行的操作的比较，请参见功能区概述。

将功能区 (XML) 项添加到项目

可以从“添加新项”对话框将“功能区(XML)”项添加到任何 Visual Studio Tools for Office 项目。Visual Studio Tools for Office 自动将以下文件添加到项目：

功能区 XML 文件。此文件定义功能区用户界面 (UI)。使用此文件添加 UI 元素，例如选项卡、组和控件等。有关详细信息，请参见本主题后面部分的功能区 XML 文件参考。
功能区代码文件。此文件包含功能区类。此类的名称与您在“添加新项”对话框中为“功能区(XML)”项指定的名称相同。Microsoft Office 应用程序使用此类的实例来加载自定义功能区。有关详细信息，请参见本主题后面部分的功能区类参考。

默认情况下，这些文件将向功能区中的“外接程序”选项卡添加一个自定义组。

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

在将“功能区(XML)”项添加到项目之后，必须将重写 CreateRibbonExtensibilityObject 方法、并将功能区 XML 类返回到 Office 应用程序的代码添加到“ThisAddin”、“ThisWorkbook”或“ThisDocument”类中。

下面的代码示例重写 CreateRibbonExtensibilityObject 方法，并返回名为 Ribbon1 的功能区 XML 类。

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

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

定义自定义功能区的行为

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

向标识代码中回调方法的功能区 XML 文件中的控件分配一个属性。
在功能区类中定义回调方法。

说明：
Outlook 2007 还需要一个额外步骤。有关更多信息，请参见自定义 Outlook 功能区。

有关演示如何在功能区中使应用程序自动化的演练，请参见演练：使用功能区 XML 创建自定义选项卡。

向控件分配回调方法

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

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

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

在属性中指定的方法可以使用任意名称。但是，该名称必须与在功能区代码文件中定义的方法的名称匹配。

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

定义回调方法

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

必须声明为公共方法。
其名称必须与为功能区 XML 文件中的控件分配的回调方法名称匹配。
其签名必须与相关功能区控件可用的回调方法类型的签名匹配。

有关功能区控件的回调方法签名的完整列表，请参见技术文章自定义 Office (2007) 功能区用户界面（针对开发人员）（第 3 部分，共 3 部分）。对于在功能区代码文件中创建的回调方法，Visual Studio Tools for Office 不提供 IntelliSense 支持。如果创建的回调方法与有效签名不符，代码仍会编译，但在用户单击该控件时不会出现任何效果。

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

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

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="https://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 文件中的默认元素。

元素	说明
customUI	表示外接程序项目中的自定义功能区。
ribbon	表示功能区。
tabs	表示一组功能区选项卡。
tab	表示单个功能区选项卡。
group	表示功能区选项卡上的一组控件。

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

属性	父元素	说明
onLoad	customUI	标识在应用程序加载功能区时调用的方法。
idMso	tab	标识要在功能区中显示的内置选项卡。
id	group	标识组。
label	group	指定在组中显示的文本。

功能区 XML 文件中的默认元素和属性是可用元素和属性的一个小子集。有关可用元素和属性的完整列表，请参见技术文章自定义 Office (2007) 功能区用户界面（针对开发人员）（第 2 部分，共 3 部分）。

功能区类参考

Visual Studio Tools for Office 在功能区代码文件中生成功能区类。将功能区上控件的回调方法添加到此类中。此类实现 Microsoft.Office.Core.IRibbonExtensibility 接口。

下表介绍此类中的默认方法。

方法	说明
GetCustomUI	返回功能区 XML 文件的内容。Microsoft Office 应用程序调用此方法来获取定义自定义功能区的用户界面的 XML 字符串。说明： GetCustomUI 应只实现为返回功能区 XML 文件的内容；它不应用于初始化外接程序。尤其是不应尝试在 GetCustomUI 实现中显示对话框或其他窗口。否则，自定义功能区可能行为不正确。如果必须运行初始化外接程序的代码，可将这些代码添加到 ThisAddIn_Startup 事件处理程序。
OnLoad	将 Microsoft.Office.Core.IRibbonControl 参数分配给 ribbon 字段。Microsoft Office 应用程序在加载自定义功能区时调用此方法。使用此字段可以动态更新自定义功能区。有关更多信息，请参见技术文章自定义 Office (2007) 功能区用户界面（针对开发人员）（第 1 部分，共 3 部分）。
GetResourceText	由 GetCustomUI 方法调用以获取功能区 XML 文件的内容。

请参见

任务

演练：使用功能区 XML 创建自定义选项卡

概念

功能区概述

Office UI 自定义

通过