将自定义 UI 添加到电子表格文档

2025-01-21

本主题演示如何使用 Open XML SDK for Office 中的类以编程方式将自定义 UI（修改功能区）添加到Microsoft Excel 工作表。它包含演示此任务的示例 AddCustomUI 方法。

创建自定义 UI

在使用 Open XML SDK 在 Excel 工作簿中创建功能区自定义之前，必须先创建自定义内容。描述创建功能区自定义项所需的 XML 超出了本主题的范围。此外，你会发现在 Visual Studio 中使用功能区Designer为你创建自定义项要容易得多。有关使用 Visual Studio 功能区Designer自定义功能区的详细信息，请参阅功能区Designer和演练：使用功能区Designer创建自定义选项卡。出于本演示的目的，你将需要一个包含自定义项的 XML 文件，以下代码提供了一个简单的自定义 (或者你可以使用 Visual Studio 功能区Designer创建自己的自定义项，然后右键单击将自定义项导出到 XML 文件) 。以下示例是此示例中使用的 xml 字符串。此 XML 内容描述了一个功能区自定义项，其中包含 Excel 选项卡上名为 Group1 的组中标有“单击我！”的 Add-Ins 按钮。单击该按钮时，它会尝试运行主机工作簿中名为 SampleMacro 的宏。

C#
Visual Basic

string xml =
@"<customUI xmlns=""http://schemas.microsoft.com/office/2006/01/customui"">
    <ribbon>
        <tabs>
            <tab idMso=""TabAddIns"">
                <group id=""Group1"" label=""Group1"">
                    <button id=""Button1"" label=""Click Me!"" showImage=""false"" onAction=""SampleMacro""/>
                </group>
            </tab>
        </tabs>
    </ribbon>
</customUI>"

Dim xml As String =
"<customUI xmlns=""http://schemas.microsoft.com/office/2006/01/customui"">
    <ribbon>
        <tabs>
            <tab idMso=""TabAddIns"">
                <group id=""Group1"" label=""Group1"">
                    <button id=""Button1"" label=""Click Me!"" showImage=""false"" onAction=""SampleMacro""/>
                </group>
            </tab>
        </tabs>
    </ribbon>
</customUI>"

创建宏

对于本演示，功能区自定义包括尝试在宿主工作簿中运行宏的按钮。若要完成该演示，必须在示例工作簿中创建宏，以便按钮的"单击"操作对其进行调用。

创建新工作簿。
按 Alt+F11 以打开 Visual Basic 编辑器。
在"插入"选项卡上，单击"模块"以创建新的模块。

将代码（如以下代码）添加到新模块。

    Sub SampleMacro(button As IRibbonControl)
        MsgBox "You Clicked?"
    End Sub

将工作簿另存为名为 AddCustomUI.xlsm 的 Excel 宏启用工作簿。

AddCustomUI 方法

方法 AddCustomUI 接受两个参数：

filename - 一个字符串，其中包含指定要修改的工作簿的文件名。
customUIContent - 包含自定义内容 (即描述自定义) 的 XML 标记的字符串。

与工作簿交互

示例方法 AddCustomUI首先在读/写模式下打开请求的工作簿，如以下代码所示。

C#
Visual Basic

using (SpreadsheetDocument document = SpreadsheetDocument.Open(fileName, true))

Using document As SpreadsheetDocument = SpreadsheetDocument.Open(fileName, True)

处理功能区可扩展部件

接下来，如以下代码所示，示例方法尝试检索对单个功能区可扩展部件的引用。如果尚不存在该部件，代码会创建一个部件并存储对该新部件的引用。

C#
Visual Basic

// You can have only a single ribbon extensibility part.
// If the part doesn't exist, create it.
RibbonExtensibilityPart part = document.RibbonExtensibilityPart ?? document.AddRibbonExtensibilityPart();

' You can have only a single ribbon extensibility part.
' If the part doesn't exist, create it.
Dim part = If(document.RibbonExtensibilityPart, document.AddRibbonExtensibilityPart())

添加自定义

给定对功能区扩展性部件的引用后，以下代码通过将部件的 CustomUI 属性设置为包含提供的自定义项的新 CustomUI 对象来结束。完成自定义后，代码会保存自定义 UI。

C#
Visual Basic

part.CustomUI = new CustomUI(customUIContent);

part.CustomUI = New CustomUI(customUIContent)

示例代码

下面是 C# 和 Visual Basic 中的完整 AddCustomUI 代码示例。传递给 AddCustomUI 的第一个参数应该是根据上述说明创建的 AddCustomUI.xlsm 文件的绝对路径。

C#
Visual Basic

static void AddCustomUI(string fileName, string customUIContent)
{
    using (SpreadsheetDocument document = SpreadsheetDocument.Open(fileName, true))
    {
        // You can have only a single ribbon extensibility part.
        // If the part doesn't exist, create it.
        RibbonExtensibilityPart part = document.RibbonExtensibilityPart ?? document.AddRibbonExtensibilityPart();

        part.CustomUI = new CustomUI(customUIContent);
    }
}

Sub AddCustomUI(fileName As String, customUIContent As String)
    Using document As SpreadsheetDocument = SpreadsheetDocument.Open(fileName, True)
        ' You can have only a single ribbon extensibility part.
        ' If the part doesn't exist, create it.
        Dim part = If(document.RibbonExtensibilityPart, document.AddRibbonExtensibilityPart())

        part.CustomUI = New CustomUI(customUIContent)
    End Using
End Sub

另请参阅

Open XML SDK 类库参考

通过