基于ASP.NET C#的Excel加载项自定义Ribbon标签不显示问题排查

算力阿峰

2026-7-2

问题

我们正在开发可在本地Office及Office 365环境运行的自定义Excel加载项，尝试为其在Ribbon中添加自定义标签。编写XML配置代码后发布，却未在Ribbon中看到自定义标签，需排查问题。

问题排查与修复方案

核心问题分析

你的XML配置存在以下关键问题，导致自定义标签无法正常加载：

缺失自定义标签相关的资源引用定义
自定义标签（CustomTab）、组、按钮使用的resid（如customTabLabel1、residCustomTabGroupLabel、paneReadButtonLabel等），未在<Resources>节点下对应定义字符串、图片、URL资源，Office无法解析这些引用，直接忽略该自定义标签。
未定义自定义控件引用的图片资源
自定义组和按钮引用的blue-icon-16、green-icon-32等图片资源，未在<bt:Images>中配置路径，加载时会触发资源缺失错误。
内置OfficeControl兼容性问题
在自定义组中嵌入<OfficeControl id="Superscript" />，部分Office版本不支持该用法，会导致自定义组加载失败。

修正后的XML配置代码

<?xml version="1.0" encoding="UTF-8"?>
<OfficeApp 
          xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0" 
          xmlns:ov="http://schemas.microsoft.com/office/taskpaneappversionoverrides"
          xsi:type="TaskPaneApp">

  <Id>52dc8a93-3686-4ea3-8e2e-2bc92714f908</Id>

  <Version>1.0.0.0</Version>
  <ProviderName>[Provider name]</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="TTSTurbo" />
  <Description DefaultValue="TTSTurbo"/>
  <IconUrl DefaultValue="~remoteAppUrl/Images/Button32x32.png" />

  <SupportUrl DefaultValue="http://www.contoso.com" />
  <AppDomains>
    <AppDomain>AppDomain1</AppDomain>
    <AppDomain>AppDomain2</AppDomain>
    <AppDomain>AppDomain3</AppDomain>
  </AppDomains>
  <Hosts>
    <Host Name="Workbook" />
  </Hosts>
  <DefaultSettings>
    <SourceLocation DefaultValue="~remoteAppUrl/Home.html" />
  </DefaultSettings>

  <Permissions>ReadWriteDocument</Permissions>

  <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
    
    <Hosts>
      <Host xsi:type="Workbook">
        <DesktopFormFactor>
          <GetStarted>
            <Title resid="Contoso.GetStarted.Title"/>

            <Description resid="Contoso.GetStarted.Description"/>
            <LearnMoreUrl resid="Contoso.GetStarted.LearnMoreUrl"/>
          </GetStarted>
          <FunctionFile resid="Contoso.DesktopFunctionFile.Url" />

          <ExtensionPoint xsi:type="PrimaryCommandSurface">
            <OfficeTab id="TabHome">
              <Group id="Contoso.Group1">
                <Label resid="Contoso.Group1Label" />
                <Icon>
                  <bt:Image size="16" resid="Contoso.tpicon_16x16" />
                  <bt:Image size="32" resid="Contoso.tpicon_32x32" />
                  <bt:Image size="80" resid="Contoso.tpicon_80x80" />
                </Icon>

                <Control xsi:type="Button" id="Contoso.TaskpaneButton">
                  <Label resid="Contoso.TaskpaneButton.Label" />
                  <Supertip>
                    <Title resid="Contoso.TaskpaneButton.Label" />
                    <Description resid="Contoso.TaskpaneButton.Tooltip" />
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="Contoso.tpicon_16x16" />
                    <bt:Image size="32" resid="Contoso.tpicon_32x32" />
                    <bt:Image size="80" resid="Contoso.tpicon_80x80" />
                  </Icon>
                  <Action xsi:type="ShowTaskpane">
                    <TaskpaneId>ButtonId1</TaskpaneId>
                    <SourceLocation resid="Contoso.Taskpane.Url" />
                  </Action>
                </Control>
              </Group>
            </OfficeTab>
            <CustomTab id="Contoso.TabCustom">
              <Group id="Contoso.TabCustom2.group2">
                <Label resid="residCustomTabGroupLabel"/>
                <Icon>
                  <bt:Image size="16" resid="blue-icon-16" />
                  <bt:Image size="32" resid="blue-icon-32" />
                  <bt:Image size="80" resid="blue-icon-80" />
                </Icon>
                <Control xsi:type="Button" id="Contoso.Button2">
                  <Label resid="paneReadButtonLabel" />
                  <Supertip>
                    <Title resid="paneReadSuperTipTitle" />
                    <Description resid="paneReadSuperTipDescription" />
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="green-icon-16" />
                    <bt:Image size="32" resid="green-icon-32" />
                    <bt:Image size="80" resid="green-icon-80" />
                  </Icon>
                  <Action xsi:type="ShowTaskpane">
                    <SourceLocation resid="readTaskPaneUrl" />
                  </Action>
                </Control>
                <!-- 暂时注释内置控件，待自定义标签正常显示后再测试兼容性 -->
                <!-- <OfficeControl id="Superscript" /> -->
              </Group>
              <Label resid="customTabLabel1" />
            </CustomTab>
          </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      <bt:Images>
        <bt:Image id="Contoso.tpicon_16x16" DefaultValue="~remoteAppUrl/Images/Button16x16.png" />
        <bt:Image id="Contoso.tpicon_32x32" DefaultValue="~remoteAppUrl/Images/Button32x32.png" />
        <bt:Image id="Contoso.tpicon_80x80" DefaultValue="~remoteAppUrl/Images/Button80x80.png" />
        <!-- 添加自定义标签所需的图片资源定义 -->
        <bt:Image id="blue-icon-16" DefaultValue="~remoteAppUrl/Images/blue-icon-16.png" />
        <bt:Image id="blue-icon-32" DefaultValue="~remoteAppUrl/Images/blue-icon-32.png" />
        <bt:Image id="blue-icon-80" DefaultValue="~remoteAppUrl/Images/blue-icon-80.png" />
        <bt:Image id="green-icon-16" DefaultValue="~remoteAppUrl/Images/green-icon-16.png" />
        <bt:Image id="green-icon-32" DefaultValue="~remoteAppUrl/Images/green-icon-32.png" />
        <bt:Image id="green-icon-80" DefaultValue="~remoteAppUrl/Images/green-icon-80.png" />
      </bt:Images>
      <bt:Urls>
        <bt:Url id="Contoso.DesktopFunctionFile.Url" DefaultValue="~remoteAppUrl/Functions/FunctionFile.html" />
        <bt:Url id="Contoso.Taskpane.Url" DefaultValue="~remoteAppUrl/Home.html" />
        <bt:Url id="Contoso.GetStarted.LearnMoreUrl" DefaultValue="https://go.microsoft.com/fwlink/?LinkId=276812" />
        <!-- 添加自定义任务窗格的URL资源 -->
        <bt:Url id="readTaskPaneUrl" DefaultValue="~remoteAppUrl/ReadPane.html" />
      </bt:Urls>
      <bt:ShortStrings>
        <bt:String id="Contoso.TaskpaneButton.Label" DefaultValue="Show Taskpane" />
        <bt:String id="Contoso.Group1Label" DefaultValue="Commands Group" />
        <bt:String id="Contoso.GetStarted.Title" DefaultValue="Get started with your sample add-in!" />
        <!-- 添加自定义标签相关的短字符串资源 -->
        <bt:String id="customTabLabel1" DefaultValue="TTSTurbo Tools" />
        <bt:String id="residCustomTabGroupLabel" DefaultValue="Data Tools" />
        <bt:String id="paneReadButtonLabel" DefaultValue="Open Read Pane" />
        <bt:String id="paneReadSuperTipTitle" DefaultValue="Open Read Pane" />
      </bt:ShortStrings>
      <bt:LongStrings>
        <bt:String id="Contoso.TaskpaneButton.Tooltip" DefaultValue="Click to Show a Taskpane" />
        <bt:String id="Contoso.GetStarted.Description" DefaultValue="Your sample add-in loaded succesfully. Go to the HOME tab and click the 'Show Taskpane' button to get started." />
        <!-- 添加自定义按钮的长字符串资源 -->
        <bt:String id="paneReadSuperTipDescription" DefaultValue="Opens a task pane for reading and analyzing data" />
      </bt:LongStrings>
    </Resources>
  </VersionOverrides>
</OfficeApp>

额外验证步骤

确保所有图片资源（如blue-icon-16.png）已放置在指定的~remoteAppUrl/Images/路径下
测试自定义标签时，先使用Office桌面客户端加载加载项，排查是否有加载错误提示
若使用Office 365，确保加载项已正确部署到租户或个人应用库中

内容的提问来源于stack exchange，提问作者Sourav Das

基于ASP.NET C#的Excel加载项自定义Ribbon标签不显示问题排查

核心问题分析 #

修正后的XML配置代码 #

额外验证步骤 #

核心问题分析

修正后的XML配置代码

额外验证步骤