功能设置扩展现在可以一次性报告多个错误,当您的 s-function-settings onSubmit 处理程序以 AggregateError 拒绝时,Shopify 管理后台会在折扣和结账规则页面上显示所有错误,而不仅仅是一个错误,无需采取任何操作。
变更内容
以前,当您的扩展在 onSubmit 中向 event.waitUntil() 传递的 Promise 拒绝时,管理后台会使用该错误的 message 显示一个错误。
现在您可以以 AggregateError 拒绝,管理后台会显示其 errors 列表中每个条目的 message,每个条目都是一个 Error,并且您可以为其提供 code 字符串。
- 管理员界面最多显示 10 条错误信息。每条消息截断为 300 个字符,重复的消息仅显示一次。
- 您的 onError 处理程序会收到带有代码的相同条目,以便您可以在自己的用户界面中标记这些字段。
- 没有 code 或代码为空且超过 64 个字符的条目将获得默认代码:折扣页面上为 UNKNOWN,结账规则页面上为 EXTENSION_ERROR。
- 以单个 Error 拒绝仍然有效并显示一个错误。
s-function-settings 的 onerror 属性现在已键入为它在 @shopify/ui-extensions 2025-10、2026-10 以及 2027-01 候选版本中接收到的 AggregateError。
受影响对象
这适用于使用 Polaris Web 组件在 API 版本 2025-10 或更高版本上构建的、在折扣或结账规则页面上具有 功能设置扩展 的应用。
早期 API 版本的扩展保持以前的行为并显示单条消息,而以单个 Error 拒绝的扩展也继续像以前一样工作。
为何重要
当商户填写多个字段出现错误时,现在只需保存一次即可看到所有问题。无需逐个修复字段、保存后再查找下一个错误。
操作指南
无需采取任何操作,要在您的 onSubmit 处理程序中报告多个错误,请以包含 Errors 的 AggregateError 进行拒绝:
function fieldError(code, message) { return Object.assign(new Error(message), {code}); } async function save(settings) { const errors = []; if (!settings.minimumQuantity) { errors.push(fieldError('MINIMUM_QUANTITY_REQUIRED', 'Enter a minimum quantity.')); } if (settings.percentage > 100) { errors.push(fieldError('PERCENTAGE_TOO_HIGH', 'Percentage can be at most 100.')); } if (errors.length > 0) { throw new AggregateError(errors, 'Settings are not valid'); } // apply your metafield changes here } <s-function-settings onSubmit={(event) => event.waitUntil(save(settings))} onError={(event) => { for (const error of event.error.errors) { console.log(error.code, error.message); } }} > {/* your fields */} </s-function-settings>此示例检查两个字段并为每个无效字段抛出一个带有 Error 的 AggregateError,请替换检查和代码为您自己的内容,要测试您的扩展,请在开发商店中保存包含多个无效字段的设置,并确认管理后台列出了每个错误。
相关文档
- 折扣功能设置 API 参考
- 使用 UI 扩展构建折扣 UI 扩展

