element.on()

2026-04-17 17:37

使用 element.on() 或 element.once() 方法为 Element 注册事件监听器。按照您的业务需求，选择以下调用场景：

如果需要持续监听，调用 element.on() 注册持续监听，事件每次触发时都会执行回调函数。
如果您希望事件只处理一次，调用 element.once() 注册一次性监听，事件触发一次后自动取消监听。

调用后，当 Element 内部触发对应事件时，会执行回调函数。

注意：事件名称与具体数据结构会因产品形态和集成场景略有不同，以下仅列出典型用法。

方法签名

调用此方法时，请使用以下标准方法签名格式：

JavaScript

element.on(event, callback);
element.once(event, callback);

TypeScript

element.on(event: string, callback: (data: EventDataType) => void): offFunction
element.once(event: string, callback: (data: EventDataType) => void): void

参数

参数名称	类型	是否必需	描述
event	String	是	事件名称，如 'error' 等。
callback	Function	是	事件回调函数，参数为该事件对应的数据对象。

error 事件

用于监听 SDK 加载的 Web 页面，其包含以下参数：

参数名称	类型	是否必需	描述
code	String	是	错误码。具体信息请参阅错误码。
message	String	是	错误信息，描述错误的具体内容。
type	String	否	错误类型，用于区分错误的分类。
detail	Any	否	错误详情，可能包含额外的调试信息。

返回值

element.on()：返回一个 offFunction 函数，调用该函数可取消本次监听。
element.once()：无返回值。该方法会在事件触发一次后自动取消监听。

错误码

以下是调用 element.on() 方法监听到的相关错误码。

element.mount() 相关

错误码	描述	后续操作
SUCCESS	成功。	无需进一步操作。
UNKNOWN_EXCEPTION	由于未知原因，方法调用失败。	提示买家确认其他方法的情况： element.mount() 阶段：前端重试后如仍不能渲染成功，请咨询 Antom 技术支持。 antom.confirmCardSetup() 阶段：尝试从服务端轮询支付结果。
PROCESS_FAIL	发生了常见的业务失败。	详细原因请咨询 Antom 技术支持。
RISK_REJECT	由于风险控制，交易无法进一步处理。如果买家已为交易付款，交易将被退款。	弹窗提示买家风险控制。
INQUIRY_PAYMENT_SESSION_FAILED	支付会话过期。	订单已超时关单，使用新的 paymentRequestId 重新发起支付。
UNKNOWN_ERROR	未知异常。	提示买家自行处理表单错误。
API_GATEWAY_TIMEOUT	网关超时。	提示买家网关超时。
API_TIMEOUT	接口响应超时。	提示买家接口响应超时。
API_GATEWAY_ERROR	网关异常。	提示买家自行处理表单错误。
MOUNT_TIMEOUT	挂载操作超时。	建议买家刷新页面重试。
MOUNT_MISSING_CONTAINER	未传入容器元素。	请确保已正确传递容器元素。
MOUNT_IFRAME_LOAD_ERROR	iframe 加载失败。	建议买家刷新页面重试。
MOUNT_NOT_SUPPORT	当前状态不支持挂载。	请避免多次挂载，或在销毁实例后再执行挂载。
MOUNT_INITIAL_FAILED	挂载初始化失败。	建议买家刷新页面重试。
MISSING_PAYMENT_METHOD	未下发渲染模板。	提示买家，详细原因请咨询 Antom 技术支持。
USER_CLOSE_VAULTING	买家关闭绑卡半浮层。	根据业务需求提示买家，或引导买家重新绑卡。

antom.createElement() 相关

错误码	描述	后续操作
NOT_SUPPORT_ELEMENT	创建了不支持的 elementType。	创建支持的 Element。
SESSION_DATA_INVALID	sessionData 无效。	排查是否使用正确的 sessionData。
ELEMENT_INIT_FAILED	Element 初始化失败。	联系 Antom 技术支持排查问题。
GENERATE_ELEMENT_KEY_FAILED	Element 唯一标识生成失败。	联系 Antom 技术支持排查问题。
CANNOT_CREATE_SAME_ELEMENT_TWICE	同时创建了两个相同的 Element。	不要创建两个相同的 Element。

antom.confirmCardSetup() 相关

错误码	描述	后续操作
SUCCESS	成功。	无需进一步操作。
UNKNOWN_EXCEPTION	由于未知原因，方法调用失败。	提示买家确认其他方法的情况： element.mount() 阶段：前端重试后如仍不能渲染成功，请咨询 Antom 技术支持。 antom.confirmCardSetup() 阶段：尝试从服务端轮询支付结果。
PAYMENT_IN_PROCESS	支付正在处理中。	提示买家确认其他方法的情况： element.mount() 阶段：前端重试后如仍不能渲染成功，请咨询 Antom 技术支持。 antom.confirmCardSetup() 阶段：尝试从服务端轮询支付结果。
USER_BALANCE_NOT_ENOUGH	由于对应支付方式的买家余额不足，支付无法完成。	弹窗提示买家余额不足。
REPEAT_REQ_REJECT	重复申请。	联系 Antom 技术支持排查问题。
ASSET_ORDER_NOT_EXIST	订单不存在。	联系 Antom 技术支持排查问题。
PROCESS_FAIL	发生了常见的业务失败。	联系 Antom 技术支持排查问题。
RISK_REJECT	由于风险控制，交易无法进一步处理。如果买家已为交易付款，交易将被退款。	弹窗提示买家风险控制。
INQUIRY_PAYMENT_SESSION_FAILED	支付会话过期。	订单已超时关单，使用新的 paymentRequestId 重新发起支付。
ACCESS_DENIED	访问被拒绝。	联系 Antom 技术支持排查问题。
CARD_EXPIRED	用于交易的银行卡已过期。	商户无需操作。
INVALID_EXPIRY_DATE_FORMAT	expiryYear 或 expiryMonth 的格式不正确。	商户无需操作。
INVALID_EXPIRATION_DATE	paymentMethod.paymentMethodMetaData.expiryYear 或 paymentMethod.paymentMethodMetaData.expiryDate 的值无效。	商户无需操作。
INVALID_CVV	用于交易的银行卡 CVV 无效。	商户无需操作。
INVALID_CARD_NUMBER	用于交易的银行卡号无效。	商户无需操作。
SELECTED_CARD_BRAND_NOT_AVAILABLE	商户指定用于交易的银行卡卡品牌不被支持。	自行排查卡品牌。
CARD_NOT_SUPPORTED	用于交易的银行卡不被支持。	商户无需操作。
CARD_BIN_QUERY_ERROR	用于交易的银行卡号无效。	商户无需操作。
VERIFICATION_IN_PROCESS	认证正在处理中。	PROCESSING 状态代表 SDK 轮询后未查询到认证结果，建议从服务端轮询支付结果。
INVALID_AMOUNT	无效金额	联系 Antom 技术支持排查问题。
CURRENCY_NOT_SUPPORT	币种不受支持。	联系 Antom 技术支持排查问题。
NO_PAY_OPTIONS	没有可用的支付选项。	联系 Antom 技术支持排查问题。
ORDER_IS_CLOSED	您发起的请求具有与已关闭交易相同的 paymentRequestId。	订单已超时关单，使用新的 paymentRequestId 重新发起支付。
PARAM_ILLEGAL	缺少必需的参数，或者存在非法参数。例如，非数字输入、无效的日期，或者参数的长度和类型错误。	联系 Antom 技术支持排查问题。
FRAUD_REJECT	由于风险控制，交易无法进一步处理。如果买家已为交易付款，交易将被退款。	如果买家在两周内未收到退款，联系 Antom 技术支持排查问题。
AUTHENTICATION_FAIL	访问被拒绝。	联系 Antom 技术支持排查问题。
PAYMENT_METHOD_SYSTEM_ERROR	由于风险控制，交易无法进一步处理。如果买家已为交易付款，交易将被退款。	如果买家在两周内未收到退款，联系 Antom 技术支持排查问题。
VERIFICATION_AMOUNT_EXCEED_LIMIT	验证金额超过限制。	联系 Antom 技术支持排查问题。
DO_NOT_HONOR	支付被发卡行拒绝。	弹窗提示买家。
UNKNOWN_ERROR	未知异常。	提示买家自行处理表单错误。
API_GATEWAY_TIMEOUT	网关超时。	提示买家网关超时。
API_TIMEOUT	接口响应超时。	提示买家接口响应超时。
API_GATEWAY_ERROR	网关异常。	提示买家自行处理表单错误。
VALIDATION_FAILED	提交时表单校验失败。	提示商户修改表单，符合后重试。
INQUIRY_RESULT_TIMEOUT	查询绑卡结果超时。	提示商户重试。
MISSING_SUCCESS_REDIRECT_URL	缺少成功后的重定向链接（redirectUrl）。	联系 Antom 技术支持排查问题。
MISSING_3D_REDIRECT_URL	缺少 3D 重定向链接。	联系 Antom 技术支持排查问题。
NOT_SUPPORT_SUBMIT	该 Element 不支持提交。	联系 Antom 技术支持排查问题。
INVALID_MODAL_URL	无效的弹窗链接（modalUrl）。	联系 Antom 技术支持排查问题。
INVALID_REDIRECT_URL	无效的重定向链接。	联系 Antom 技术支持排查问题。
DDC_UPLOAD_PARAM_ILLEGAL	3DE 的 DDC 异常，DDC 上传参数错误。	联系 Antom 技术支持排查问题。
DDC_UPLOAD_DATA_FAILED	3DE 的 DDC 异常，FORM 表单提交时渠道页面异常。	联系 Antom 技术支持排查问题。
DDC_QUERY_ID_MISSING	3DE 的 DDC 异常，ddcquery 查询结果不符合要求，无 ID。	联系 Antom 技术支持排查问题。
DDC_QUERY_INFO_MISSING	3DE 的 DDC 异常，ddcquery 查询结果不符合要求，无 ddcInf。	联系 Antom 技术支持排查问题。
DDC_QUERY_INFO_UUID_MISSING	3DE 的 DDC 异常，缺少 ddcSubmit 的必要参数。	联系 Antom 技术支持排查问题。
DDC_PARAMETERS_INVALID	3DE 的 DDC 异常，缺少 3de 前置必要参数。	联系 Antom 技术支持排查问题。
DDC_INQUIRY_3D_REDIRECT_URL_PARAMS_MISSING	3DE 的 DDC 异常，缺少 3de 链接查询必要参数。	联系 Antom 技术支持排查问题。
DDC_QUERY_PAYMENT_REDIRECT_URL_TIMEOUT	3DE 的 DDC 异常，ddc 查询重定向链接超时。	联系 Antom 技术支持排查问题。

最佳实践

事件名大小写敏感：请严格按照文档或 SDK 定义的事件名传入。
多次注册：对同一事件多次调用 element.on() 会注册多个监听器，均将按照注册的顺序被触发。如不再需要，请结合业务需求自行管理或通过其他 API 取消监听。
销毁时机：调用 element.destroy() 或 element.unmount() 后，对应 Element 的事件监听器将不再生效。