Office.onReady在Microsoft加载项初始化时不运行，如何无需显示任务窗格调用？

开发者阿泽

2026-7-27

问题

我正在开发基于React的Microsoft Office Add-in TaskPane项目，采用TypeScript语言，且已启用Shared Runtime。当前遇到的问题是：只有显示任务窗格时office.js才会初始化，Office.onReady也才会被调用。请问如何在不显示任务窗格的情况下调用Office.onReady？

清单文件（Manifest）

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<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>81d7e91a-c8e6-454f-806a-9b84cf3e7dd5</Id>
  <Version>1.0.0.0</Version>
  <ProviderName>Contoso</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="Add-in"/>
  <Description DefaultValue="A template to get started."/>
  <IconUrl DefaultValue="https://localhost:3000/assets/login_32.png"/>
  <HighResolutionIconUrl DefaultValue="https://localhost:3000/assets/login.png"/>
  <SupportUrl DefaultValue="https://www.contoso.com/help"/>
  <AppDomains>
    <AppDomain>https://www.contoso.com</AppDomain>
  </AppDomains>
  <Hosts>
    <Host Name="Workbook"/>
  </Hosts>
  <Requirements>
    <Sets DefaultMinVersion="1.1">
      <Set Name="SharedRuntime" MinVersion="1.1"/>
    </Sets>
  </Requirements>
  <DefaultSettings>
    <SourceLocation DefaultValue="https://localhost:3000/taskpane.html"/>
  </DefaultSettings>
  <Permissions>ReadWriteDocument</Permissions>
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
    <Hosts>
      <Host xsi:type="Workbook">
        <Runtimes>
          <Runtime resid="Taskpane.Url" lifetime="long" />
        </Runtimes>
        <DesktopFormFactor>
          <GetStarted>
            <Title resid="GetStarted.Title"/>
            <Description resid="GetStarted.Description"/>
            <LearnMoreUrl resid="GetStarted.LearnMoreUrl"/>
          </GetStarted>
          <FunctionFile resid="Taskpane.Url"/>
          <ExtensionPoint xsi:type="CustomFunctions">
            <Script>
              <SourceLocation resid="Taskpane.Url"/>
            </Script>
            <Page>
              <SourceLocation resid="Taskpane.Url"/>
            </Page>
            <Metadata>
              <SourceLocation resid="Functions.Metadata.Url"/>
            </Metadata>
          </ExtensionPoint>
          <ExtensionPoint xsi:type="PrimaryCommandSurface">
            <CustomTab id="CustomTab">
              <Group id="AuthGroup">
                <Label resid="AuthGroupNameLabel" />
                <Icon>
                  <bt:Image size="16" resid="Group1LoginIcon16" />
                  <bt:Image size="32" resid="Group1LoginIcon32" />
                  <bt:Image size="80" resid="Group1LoginIcon80" />
                </Icon>
                <Control xsi:type="Button" id="BtnOpenTaskpane">
                  <Label resid="LoginButtonLabel" />
                  <Supertip>
                    <Title resid="LoginButtonToolTipTitle" />
                    <Description resid="LoginButtonToolTipDescription" />
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="Group1LoginIcon16" />
                    <bt:Image size="32" resid="Group1LoginIcon32" />
                    <bt:Image size="80" resid="Group1LoginIcon80" />
                  </Icon>
                  <Action xsi:type="ExecuteFunction">
                                        <FunctionName>btnopentaskpane</FunctionName>
                                    </Action>
                </Control>
                <Control xsi:type="Button" id="BtnCloseTaskpane">
                                    <Label resid="LogoutButtonLabel" />
                                    <Supertip>
                                        <Title resid="LogoutButtonToolTipTitle" />
                                        <Description resid="LogoutButtonToolTipDescription" />
                                    </Supertip>
                                    <Icon>
                                        <bt:Image size="16" resid="Group1Logout"/>
                                        <bt:Image size="32" resid="Group1Logout"/>
                                        <bt:Image size="80" resid="Group1Logout"/>
                                    </Icon>
                                    <Action xsi:type="ExecuteFunction">
                                        <FunctionName>btnclosetaskpane</FunctionName>
                                    </Action>
                  <Enabled>false</Enabled>
                                </Control>
              </Group>
              <Label resid="ribbonNameLabel" />
            </CustomTab>
          </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      <bt:Images>
        <bt:Image id="Group1LoginIcon16" DefaultValue="https://localhost:3000/assets/login_16.png"/>
        <bt:Image id="Group1LoginIcon32" DefaultValue="https://localhost:3000/assets/login_32.png"/>
        <bt:Image id="Group1LoginIcon80" DefaultValue="https://localhost:3000/assets/login.png"/>
        <bt:Image id="Group1Logout" DefaultValue="https://localhost:3000/assets/logout.png"/>
      </bt:Images>
      <bt:Urls>
        <bt:Url id="GetStarted.LearnMoreUrl" DefaultValue="https://go.microsoft.com/fwlink/?LinkId=276812"/>
        <bt:Url id="Commands.Url" DefaultValue="https://localhost:3000/commands.html"/>
        <bt:Url id="LoginTaskPaneUrl" DefaultValue="https://localhost:3000/taskpane.html"/>
        <bt:Url id="Functions.Script.Url" DefaultValue="https://localhost:3000/public/functions.js"/>
        <bt:Url id="Functions.Metadata.Url" DefaultValue="https://localhost:3000/public/functions.json"/>
        <bt:Url id="Taskpane.Url" DefaultValue="https://localhost:3000/taskpane.html"/>
      </bt:Urls>
      <bt:ShortStrings>
        <bt:String id="GetStarted.Title" DefaultValue="Get started with your sample add-in!"/>
        <bt:String id="ribbonNameLabel" DefaultValue="Add-in"/>
        <bt:String id="AuthGroupNameLabel" DefaultValue="Auth"/>
        <bt:String id="LoginButtonLabel" DefaultValue="Login" />
        <bt:String id="LogoutButtonLabel" DefaultValue="Logout" />
        <bt:String id="LoginTaskPaneTitle" DefaultValue="Login" />
        <bt:String id="LoginButtonToolTipTitle" DefaultValue="Tooltip Title Login" />
        <bt:String id="LogoutButtonToolTipTitle" DefaultValue="Tooltip Title Logout" />
      </bt:ShortStrings>
      <bt:LongStrings>
        <bt:String id="GetStarted.Description" DefaultValue="Welcome to Add-in"/>
        <bt:String id="LoginButtonToolTipDescription" DefaultValue="Tooltip Description Login" />
        <bt:String id="LogoutButtonToolTipDescription" DefaultValue="Tooltip Description Logout" />
      </bt:LongStrings>
    </Resources>
  </VersionOverrides>
</OfficeApp>

当前代码逻辑

我通过点击功能区上的登录按钮来显示任务窗格：

//command.ts
Office.onReady(async (info) => {
  if (info.host === Office.HostType.Excel) {
    console.log("ensure state initialized from the office.initialize");
  }
});

async function btnOpenTaskpane(event) {
  console.log("Open task pane button pressed");
  Office.addin.showAsTaskpane();
  event.completed();
}

环境信息

Excel Office 365
Windows 10 Pro

解决方案

1. 修改清单文件配置共享运行时加载行为

在清单的Runtimes节点中，为Runtime标签添加loadBehavior="load"属性。这个配置会让Excel在启动时自动加载共享运行时，无需等待任务窗格显示：

<Runtimes>
  <Runtime resid="Taskpane.Url" lifetime="long" loadBehavior="load" />
</Runtimes>

2. 保留现有初始化逻辑

你的Office.onReady已经在command.ts中正确注册，只要共享运行时加载完成，这个回调就会自动触发，和任务窗格是否显示无关。不需要额外修改代码逻辑，保持当前的注册方式即可。

3. 验证效果

重新部署加载项后，打开Excel：

无需点击任何按钮打开任务窗格
通过Office加载项调试工具查看控制台，应该能看到ensure state initialized from the office.initialize的日志输出，说明Office.onReady已成功触发

内容的提问来源于stack exchange，提问作者vibhor Gupta

Office.onReady在Microsoft加载项初始化时不运行，如何无需显示任务窗格调用？

清单文件（Manifest） #

当前代码逻辑 #

环境信息 #

解决方案 #

1. 修改清单文件配置共享运行时加载行为 #

2. 保留现有初始化逻辑 #

3. 验证效果 #