本教程详细介绍了如何在 Magento 2 结账流程中为城市和街道字段实现自定义验证。我们将通过创建一个自定义模块，利用 Magento 2 的 UI 组件和附加验证器机制，在不直接修改 Knockout HTML 模板的情况下，实现对用户输入地址信息的有效校验，并展示如何获取字段值及显示错误信息。
Magento 2 结账验证机制概述
在 Magento 2 中，结账页面大量使用了 Knockout.js 框架进行动态渲染。这意味着前端模板（.html 文件）是纯客户端渲染的，无法直接嵌入 PHP 代码来生成动态 URL 或执行服务器端逻辑。如果需要进行自定义验证，特别是涉及服务器端数据（如城市列表）的验证，我们不能像传统 PHP 模板那样直接在 .html 文件中混合 PHP 和 JavaScript。
Magento 2 提供了一种更优雅且可扩展的方式来处理结账流程中的验证：附加验证器 (additional validators)。通过这种机制，我们可以在结账步骤（例如支付信息步骤）注册自定义的 JavaScript 验证逻辑，这些逻辑会在用户尝试进入下一步或提交订单时被触发。这种方法避免了直接修改核心模板，保证了代码的健壮性和可维护性。
创建自定义验证模块
首先，我们需要创建一个 Magento 2 自定义模块。假设模块名为 Vendor_MyCheckoutValidator。
-
创建模块定义文件 module.xml: 在 app/code/Vendor/MyCheckoutValidator/etc/module.xml 中创建以下内容：
<?xml version="1.0"?> <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd"> <module name="Vendor_MyCheckoutValidator" setup_version="1.0.0"> <sequence> <module name="Magento_Checkout"/> </sequence> </module> </config> -
创建注册文件 registration.php: 在 app/code/Vendor/MyCheckoutValidator/registration.php 中创建以下内容：
<?php \Magento\Framework\Component\ComponentRegistrar::register( \Magento\Framework\Component\ComponentRegistrar::MODULE, 'Vendor_MyCheckoutValidator', __DIR__ ); 启用模块: 运行 php bin/magento setup:upgrade 和 php bin/magento cache:clean。
注入自定义验证器
为了让 Magento 知道我们的自定义验证逻辑，我们需要在结账布局中注册它。我们将通过复制并修改 Magento_Checkout 模块的 checkout_index_index.xml 文件来完成。
-
创建布局文件: 在 app/code/Vendor/MyCheckoutValidator/view/frontend/layout/checkout_index_index.xml 中创建以下内容。这里我们只保留必要的结构，以在支付步骤的 additional-payment-validators 中添加我们的验证器。
<?xml version="1.0"?> <page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" layout="1column" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd"> <body> <referenceBlock name="checkout.root"> <arguments> <argument name="jsLayout" xsi:type="array"> <item name="components" xsi:type="array"> <item name="checkout" xsi:type="array"> <item name="children" xsi:type="array"> <item name="steps" xsi:type="array"> <item name="children" xsi:type="array"> <!-- ... 其他步骤配置 ... --> <item name="billing-step" xsi:type="array"> <item name="children" xsi:type="array"> <item name="payment" xsi:type="array"> <item name="children" xsi:type="array"> <item name="additional-payment-validators" xsi:type="array"> <item name="children" xsi:type="array"> <!-- 注册我们的自定义城市验证器 --> <item name="my-city-validator" xsi:type="array"> <item name="component" xsi:type="string">Vendor_MyCheckoutValidator/js/view/finalcheck-validation</item> </item> </item> </item> </item> </item> </item> </item> </item> </item> </item> </item> </item> </argument> </arguments> </referenceBlock> </body> </page>注意: 如果你需要在配送步骤进行验证，则需要修改 shipping-step 下的相应节点。
实现自定义 UI 组件
接下来，我们创建 finalcheck-validation.js 文件，它将作为 UI 组件来注册我们的实际验证逻辑。
在 app/code/Vendor/MyCheckoutValidator/view/frontend/web/js/view/finalcheck-validation.js 中创建：
define(
[
'uiComponent',
'Magento_Checkout/js/model/payment/additional-validators',
'Vendor_MyCheckoutValidator/js/model/final-address-check-validator' // 引用实际的验证逻辑
],
function (Component, additionalValidators, finalAddressCheckValidator) {
'use strict';
// 将我们的自定义验证器注册到 Magento 的附加验证器列表中
additionalValidators.registerValidator(finalAddressCheckValidator);
return Component.extend({});
}
);这个文件非常简洁，它的主要作用就是导入 additionalValidators 和我们的核心验证逻辑 finalAddressCheckValidator，然后调用 registerValidator 方法将其注册到系统中。
编写核心验证逻辑
现在，我们来创建包含实际验证规则的 final-address-check-validator.js 文件。
在 app/code/Vendor/MyCheckoutValidator/view/frontend/web/js/model/final-address-check-validator.js 中创建：
define(
[
'jquery',
'mage/translate',
'Magento_Ui/js/model/messageList' // 用于显示错误消息
],
function ($, $t, messageList) {
'use strict';
return {
/**
* 验证函数，Magento 会在结账时调用
* @returns {boolean} 如果验证通过返回 true，否则返回 false
*/
validate: function () {
var cityIsFine = true,
// 通过 input 的 name 属性获取城市输入框的值
city = $('input[name="city"]').val();
// 示例验证逻辑：如果城市以 'Z' 开头，则视为无效
if (city && city.match(/^Z/)) {
messageList.addErrorMessage({ message: $t('We are sorry, your city starts with a Z. This is not allowed.') });
cityIsFine = false;
}
// 示例：获取街道字段的值
// 街道字段通常是数组形式，例如 street[0], street[1]
var streetLine1 = $('input[name="street[0]"]').val();
// 如果有更多街道行，可以继续获取，例如：
// var streetLine2 = $('input[name="street[1]"]').val();
console.log('City entered:', city);
console.log('Street Line 1 entered:', streetLine1);
// 在此处可以添加更多复杂的验证逻辑，包括 AJAX 请求
// 例如，可以发起 AJAX 请求到服务器验证城市是否在允许列表中
if (!cityIsFine) {
return false; // 验证失败
}
return true; // 验证通过
}
};
}
);代码解析与注意事项：
- 获取字段值: 我们使用 $('input[name="city"]').val() 来获取城市输入框的值。对于街道字段，通常是 street[0]、street[1] 等，因此可以使用 $('input[name="street[0]"]').val() 来获取。
- 错误消息: Magento_Ui/js/model/messageList 是 Magento 2 中用于显示系统消息的组件。通过 messageList.addErrorMessage({ message: $t('你的自定义错误消息') }) 可以将错误信息显示在页面顶部。$t 函数用于翻译字符串。
- AJAX 请求: 如果你需要根据服务器端的城市列表进行验证或提供自动补全功能，可以在 validate 方法内部发起 AJAX 请求。例如，使用 $.ajax()。然而，请注意，自动补全通常需要更复杂的 UI 交互，可能需要自定义 Knockout 模板或使用现有的 UI 组件进行扩展。本教程主要侧重于验证逻辑。
- 返回布尔值: validate 函数必须返回 true（验证通过）或 false（验证失败）。如果返回 false，结账流程将停止，并显示错误消息。
部署与测试
完成上述文件创建后，需要进行以下操作：
- 清除缓存: php bin/magento cache:clean 和 php bin/magento cache:flush。
- 静态内容部署: php bin/magento setup:static-content:deploy -f (在开发模式下可能需要，生产模式下必须)。
- 清除浏览器缓存: 确保浏览器加载的是最新的 JavaScript 文件。
现在，访问你的 Magento 2 商店结账页面。在支付信息步骤填写地址时，尝试输入一个以 'Z' 开头的城市（例如 "Zenith"）。当你点击“继续支付”或类似按钮时，如果城市以 'Z' 开头，系统将显示错误消息，并且无法继续。
总结
通过上述步骤，我们成功地为 Magento 2 结账页面的城市和街道字段实现了自定义验证。这种方法利用了 Magento 2 的 UI 组件和附加验证器机制，避免了对 Knockout HTML 模板的直接修改，提供了一个可维护且符合 Magento 最佳实践的解决方案。
虽然本教程主要关注验证逻辑，但其核心思想——通过自定义 JavaScript 组件注入逻辑——同样适用于更复杂的交互需求，如基于 AJAX 的城市/街道自动补全。对于自动补全功能，通常需要结合自定义 Knockout 绑定或 UI 组件，使其能够动态地展示建议列表。
