通过

Ribbon XML

  • 项目

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

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

向项目添加功能区 (XML) 项

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

  • 功能区 XML 文件。 此文件定义功能区用户界面 (UI)。 使用此文件添加 UI 元素，例如选项卡、组和控件。 有关详细信息，请参阅本主题稍后将介绍的功能区 XML 文件引用。

  • 功能区代码文件。 此文件包含 功能区类。 此类的名称即你在 “添加新项” 对话框中为 “功能区 (XML)” 项指定的名称。 Microsoft Office 应用程序使用此类的实例来加载自定义功能区。 有关详细信息，请参阅本主题稍后将介绍的功能区类引用。

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

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

将功能区 (XML) 项添加到项目后，必须将代码添加到 ThisAddin、ThisWorkbook 或 ThisDocument 类，该类替代 CreateRibbonExtensibilityObject 方法，并将功能区 XML 类返回到 Office 应用程序。

下面的代码示例替代 CreateRibbonExtensibilityObject 方法并返回名为 MyRibbon 的功能区 XML 类。

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

定义自定义功能区的行为

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

  • 将特性分配给功能区 XML 文件中的控件，该文件标识代码中的回叫方法。

  • 定义功能区类中的回叫方法。

注意

Outlook 还需要一个额外的步骤。 有关详细信息，请参阅自定义 Outlook 功能区。

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

将回调方法分配给控件

若要将回叫方法分配给功能区 XML 文件中的控件，添加指定回叫方法类型和方法名称的特性。 例如，下面的元素定义具有名为 OnToggleButton1 的 OnToggleButton1。

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

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

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

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

定义回调方法

定义功能区代码文件中功能区类中的回叫方法。 回叫方法具有以下几个要求：

  • 它必须声明为公共。

  • 其名称必须匹配分配给功能区 XML 文件中控件的回叫方法的名称。

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

    有关功能区控件的回调方法签名的完整列表，请参阅技术文章为开发人员自定义 Office (2007) 功能区用户界面（第 3 部分，共 3 部分）。 Visual Studio 不对在功能区代码文件中创建的回叫方法提供 IntelliSense 支持。 如果创建的回叫方法与有效签名不匹配，代码虽然能够编译，但当用户单击控件时不会执行任何操作。

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

    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 文件中的默认元素。

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

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

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

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

功能区类引用

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

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

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

相关内容