使用特定于应用程序的 JavaScript API 进行错误处理

使用特定于应用程序的 Office JavaScript API 生成加载项时，请确保包含错误处理逻辑以说明运行时错误。由于 API 的异步特性，这样做至关重要。

最佳做法

在我们的代码示例和 Script Lab 片段中，你会注意到每次调用 Excel.run、 PowerPoint.run或 Word.run 都伴随一个catch语句以捕获任何错误。建议在使用特定于应用程序的 API 生成加载项时使用相同的模式。

$("#run").on("click", () => tryCatch(run));

async function run() {
  await Excel.run(async (context) => {
      // Add your Excel JavaScript API calls here.

      // Await the completion of context.sync() before continuing.
    await context.sync();
    console.log("Finished!");
  });
}

/** Default helper for invoking an action and handling errors. */
async function tryCatch(callback) {
  try {
    await callback();
  } catch (error) {
    // Note: In a production add-in, you'd want to notify the user through your add-in's UI.
    console.error(error);
  }
}

API 错误

当 Office JavaScript API 请求未成功运行时，API 将返回包含以下属性的错误对象。

代码：code错误消息的属性包含一个字符串，该字符串OfficeExtension.ErrorCodes{application}.ErrorCodes属于 {application} 或 Excel、PowerPoint 或 Word。例如，错误代码“InvalidReference”指示引用对于指定操作无效。错误代码尚未本地化。
消息：错误消息的 message 属性包含本地化字符串中的错误摘要。该错误消息不适用于最终用户;您应使用错误代码和适当的业务逻辑来确定加载项向最终用户显示的错误消息。
debugInfo：出现此信息时，错误消息的 debugInfo 属性将提供其他信息，帮助理解错误根本原因。

注意

如果您用于 console.log() 将错误消息打印到控制台，则这些消息仅在服务器上可见。最终用户在加载项任务窗格或 Office 应用程序中的任何位置都看不到这些错误消息。若要向用户报告错误，请参阅错误通知。

错误代码和消息

下表列出了特定于应用程序的 API 可能返回的错误。

注意

下表列出了使用特定于应用程序的 API 时可能遇到的错误消息。如果正在使用通用 API，请参阅 Office 通用 API 错误代码以了解相关的错误消息。

错误代码	错误消息	注释
`AccessDenied`	无法执行所请求的操作。	这可能是因为用户的防病毒软件阻止了 Office 的某些部分。有关更多指导，请参阅“错误：拒绝访问”的常见错误和故障排除步骤。
`ActivityLimitReached`	已达到活动限制。	无
`ApiNotAvailable`	请求的 API 不可用。	无
`ApiNotFound`	找不到你尝试使用的 API。它可能在较新版本的 Office 应用程序中可用。有关详细信息，请参阅 Office 客户端应用程序和 Office 加载项的平台可用性。	无
`BadPassword`	你提供的密码不正确。	无
`Conflict`	由于冲突，无法处理请求。	无
`ContentLengthRequired`	`Content-length`缺少 HTTP 标头。	无
`GeneralException`	处理请求时出现内部错误。	无
`HostRestartNeeded`	Office 应用程序需要重新启动。	如果自 Office 应用程序启动后已更新调用该方法的加载项，则 Office.ribbon.requestUpdate () 方法会出现此错误。
`InsertDeleteConflict`	尝试的插入或删除操作导致冲突。	无
`InvalidArgument`	自变量无效、缺少或格式不正确。	无
`InvalidBinding`	由于之前的更新，此对象绑定不再有效。	无
`InvalidOperation`	尝试的操作对于对象无效。	无
`InvalidReference`	此引用对于当前操作无效。	无
`InvalidRequest`	无法处理此请求。	无
`InvalidRibbonDefinition`	给出 Office 的功能区定义无效。	如果将无效的 RibbonUpdateObject 传递到 Office.ribbon.requestUpdate () 方法，则会引发此错误。
`InvalidSelection`	当前选定内容对于此操作无效。	无
`ItemAlreadyExists`	所创建的资源已存在。	无
`ItemNotFound`	所请求的资源不存在。	无
`MemoryLimitReached`	已达到内存限制。无法完成你的操作。	无
`NotImplemented`	所请求的功能未实现。	这可能意味着 API 处于预览状态或仅在特定平台 (（例如仅联机) ）上受支持。有关详细信息，请参阅 Office 客户端应用程序和 Office 加载项的平台可用性。
`RequestAborted`	请求在运行时已中止。	无
`RequestPayloadSizeLimitExceeded`	请求有效负载大小已超出限制。有关详细信息，请参阅 Office 加载项的资源限制和性能优化一文。	此错误仅发生在 Office web 版中。
`ResponsePayloadSizeLimitExceeded`	响应有效负载已超出限制。有关详细信息，请参阅 Office 加载项的资源限制和性能优化一文。	此错误仅发生在 Office web 版中。
`ServiceNotAvailable`	服务不可用。	无
`Unauthenticated`	所需的身份验证信息缺少或无效。	无
`UnsupportedFeature`	操作失败，因为源工作表包含一个或多个不受支持的功能。	无
`UnsupportedOperation`	不支持正在尝试的操作。	无

Excel 特定的错误代码和消息

错误代码	错误消息	注释
`EmptyChartSeries`	尝试的操作失败，因为图表系列为空。	无
`FilteredRangeConflict`	尝试的操作导致与筛选范围冲突。	无
`FormulaLengthExceedsLimit`	所应用公式的字节码超过最大长度限制。对于 32 位计算机上的 Office，字节码长度限制为 16384 个字符。在 64 位计算机上，字节码长度限制为 32768 个字符。	此错误同时出现在 Excel web 版和桌面版中。
`GeneralException`	各种。	数据类型 API 返回 `GeneralException` 带有动态错误消息的错误。这些消息引用作为错误源的单元格以及导致错误的问题，例如：“单元格 A1 缺少所需的属性 `type`”。
`InactiveWorkbook`	操作失败，因为打开了多个工作簿，并且此 API 调用的工作簿已失去焦点。	无
`InvalidOperationInCellEditMode`	当 Excel 处于“编辑单元格”模式时，该操作不可用。使用 `Enter` 键或 `Tab` 键，或选择另一个单元格退出编辑模式，然后重试。	无
`MergedRangeConflict`	无法完成此操作。表不得与其他表、数据透视表、查询结果、合并单元格或 XML 映射重叠。	无
`NonBlankCellOffSheet`	Microsoft Excel 无法插入新单元格，因为它会将非空单元格推到工作表末尾。这些非空单元格可能显示为空，但具有空白值、一些格式或公式。删除足够多的行或列，以便为要插入的内容腾出空间，然后重试。	无
`OperationCellsExceedLimit`	尝试的操作影响的单元格数量超过 33554000 个上限。	如果触发 `TableColumnCollection.add API` 此错误，请确认工作表内但在表外没有无意数据。特别是，检查工作表最右侧列中的数据。删除意外数据以解决此错误。验证操作处理多少个单元格的一种方法是运行以下计算： `(number of table rows) x (16383 - (number of table columns))`. 数字 16383 是 Excel 支持的最大列数。此错误仅发生在 Excel web 版中。
`PivotTableRangeConflict`	尝试的操作导致与数据透视表范围发生冲突。	无
`RangeExceedsLimit`	范围内的单元格计数已超过支持的最大数量。有关详细信息，请参阅 Office 加载项的资源限制和性能优化一文。	无
`RefreshWorkbookLinksBlocked`	操作失败，因为用户未授予刷新外部工作簿链接的权限。	无
`UndoNotSupported`	由于缺少对撤销操作的支持，JavaScript API 请求失败。	无
`UnsupportedSheet`	此工作表类型不支持此操作，因为它是宏或图表工作表。	无

特定于 Word 的错误代码和消息

错误代码	错误消息	注释
`SearchDialogIsOpen`	此时将打开搜索对话框。	无
`SearchStringInvalidOrTooLong`	搜索字符串无效或过长。	搜索字符串最大值为 255 个字符。

错误通知

如何向用户报告错误取决于你正在使用的 UI 系统。

如果使用 React 作为 UI 系统，请使用 Fluent UI 组件和设计元素。建议使用对话框组件传达错误消息。如果错误存在于用户的输入中，则配置输入组件以将错误显示为粗体红色文本。

注意

警报组件还可用于向用户报告错误，但它目前处于预览状态，不应在生产加载项中使用。有关其发布状态的信息，请参阅 Fluent UI React v9 组件路线图。
如果您没有将 React 用于 UI，请考虑使用直接在 HTML 和 JavaScript 中实现的旧版 Fabric UI 组件。

另请参阅

反馈

此页面是否有帮助？

Last updated on 2026-09-02