Angular版Yeoman任务窗格Office Add-in自定义函数添加问题排查

1. 补全manifest.xml的Shared Runtime配置 #

• 得在<VersionOverrides>里同时配置任务窗格和自定义函数的Runtime规则，必须指定SharedRuntime，且相关资源路径要对齐：

  <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
    <Hosts>
      <Host xsi:type="Workbook">
        <Runtimes>
          <!-- ID统一，类型设为SharedRuntime，生命周期选long -->
          <Runtime resid="Taskpane.Url" type="SharedRuntime" lifetime="long" />
        </Runtimes>
        <DesktopFormFactor>
          <!-- 自定义函数入口与任务窗格共用同一URL -->
          <FunctionFile resid="Taskpane.Url"/>
          <!-- 添加自定义函数扩展点，命名空间和函数声明要与代码对应 -->
          <ExtensionPoint xsi:type="CustomFunctions">
            <Script>
              <SourceLocation resid="Taskpane.Url"/>
            </Script>
            <Page>
              <SourceLocation resid="Taskpane.Url"/>
            </Page>
            <Namespace resid="Functions.Namespace"/>
            <Function name="ADD" description="两数相加">
              <Parameters>
                <Parameter name="first" type="number"/>
                <Parameter name="second" type="number"/>
              </Parameters>
              <ReturnValue type="number"/>
            </Function>
          </ExtensionPoint>
          <!-- 保留原有任务窗格的GetStarted等配置 -->
        </DesktopFormFactor>
      </Host>
    </Hosts>
  </VersionOverrides>
  

  别忘了检查<Resources>节点里的resid对应的URL是否正确指向任务窗格的打包文件。

2. 调整webpack.config.js的打包规则 #

• 不用单独给自定义函数设置入口，直接在任务窗格入口文件中导入自定义函数代码即可，比如在src/taskpane/taskpane.ts中添加：

  import './custom-functions';
  

• 如果之前开启了代码拆分（splitChunks），建议先临时关闭，Shared Runtime对chunk加载的兼容性有限：

  module.exports = {
    entry: {
      polyfill: ['core-js/stable', 'regenerator-runtime/runtime'],
      taskpane: './src/taskpane/taskpane.ts',
      // 删除单独的custom-functions入口项
    },
    optimization: {
      splitChunks: false, // 先禁用拆分排查问题
    },
    // 其他配置保持不变
  };
  

3. 规范自定义函数的注册逻辑 #

• custom-functions.ts中的函数必须用CustomFunctions.associate绑定，且命名空间要与manifest一致，同时要规避Angular Zone的干扰：

  /* global CustomFunctions */
  import { NgZone } from '@angular/core';
  
  // 定义纯函数逻辑
  function add(first: number, second: number): number {
    return first + second;
  }
  
  // 在Angular上下文外执行，避免变更检测影响
  const ngZone = new NgZone({ enableLongStackTrace: false });
  CustomFunctions.associate("ADD", (first, second) => {
    return ngZone.runOutsideAngular(() => add(first, second));
  });
  

  注意：自定义函数不要直接调用Angular组件或服务，如需传递数据，可通过Shared Runtime的全局对象（如window）中转。

4. 确认Office初始化流程无阻塞 #

• 在taskpane.ts中，确保Office初始化完成后再加载Angular应用，不要让Angular启动阻塞自定义函数的注册：

  Office.initialize = () => {
    // 自定义函数已通过导入自动注册，无需额外操作
    platformBrowserDynamic().bootstrapModule(AppModule)
      .catch(err => console.error(err));
  };
  

5. 测试阶段的注意事项 #

• 启动项目后，在Excel中调用自定义函数必须带上命名空间，比如=MYNAMESPACE.ADD(1,2)，不能直接写=ADD(1,2)
• 打开Excel开发者工具（文件>选项>自定义功能区>勾选开发者），查看控制台是否有加载失败、函数未注册等报错信息
• 确保使用的Office版本支持Shared Runtime，建议升级到最新测试版

内容的提问来源于stack exchange，提问作者Ruturaj Maggirwar