本教程旨在指导如何在Magento 2结账页为城市和街道输入字段实现自定义验证功能。我们将深入探讨如何利用Magento的ui组件和附加验证器机制，避免在Knockout.js模板中直接嵌入php代码的限制。文章将涵盖xml配置、javaScript组件创建、验证逻辑编写，并简要讨论如何通过ajax实现自动补全功能的思路。
引言：Magento 2 结账页自定义验证挑战
Magento 2 的前端结账页是基于 Knockout.js 和 UI 组件构建的，这种架构提供了高度的灵活性和模块化，但也引入了一些在传统mvc模式下不常见的设计模式。其中一个常见的挑战是，当需要对城市或街道等输入字段进行自定义验证，甚至实现自动补全功能时，开发者可能会遇到难以在 .html 模板中直接嵌入 PHP 代码以获取动态数据（如 AJAX 请求 URL）的问题。这是因为 Knockout 模板通常是纯 html，不直接支持服务器端脚本。
本教程将提供一个专业的解决方案，通过利用 Magento 2 的 UI 组件系统和“附加验证器”机制，实现结账页的自定义验证。这种方法不仅规避了模板中嵌入 PHP 的问题，还符合 Magento 2 的最佳实践。
核心概念：附加验证器 (Additional Validators)
Magento 2 结账页提供了一个强大的“附加验证器”机制，允许开发者在不直接修改核心文件或覆盖现有 UI 组件的情况下，为结账流程中的特定步骤（如运输信息或支付信息）添加自定义验证逻辑。这些验证器会在用户尝试进入下一步或提交表单时触发。
步骤一：创建自定义模块
首先，我们需要创建一个自定义 Magento 模块来承载我们的验证逻辑。假设模块名为 Vendor_MyCheckoutValidator。
在 app/code/Vendor/MyCheckoutValidator 目录下创建以下文件：
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>
app/code/Vendor/MyCheckoutValidator/registration.php:
<?php MagentoFrameworkComponentComponentRegistrar::register( MagentoFrameworkComponentComponentRegistrar::MODULE, 'Vendor_MyCheckoutValidator', __DIR__ );
步骤二：注册自定义验证器组件
接下来，我们需要在结账页的布局 XML 文件中注册我们的自定义验证器组件。我们将以支付步骤为例，在支付验证器列表中添加一个新项。
在您的自定义模块中创建或修改 checkout_index_index.xml 文件：
app/code/Vendor/MyCheckoutValidator/view/frontend/layout/checkout_index_index.xml:
<?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>
说明： 我们通过 referenceBlock name=”checkout.root” 找到结账页的根组件，然后沿着 jsLayout 路径，在 billing-step -> payment -> additional-payment-validators 下添加了一个名为 my-city-validator 的新项。这个项指向了我们即将创建的 javascript UI 组件 Vendor_MyCheckoutValidator/js/view/finalcheck-validation。
步骤三：实现验证器入口组件
这个 JavaScript 文件是一个 UI 组件，它的主要作用是将我们的实际验证逻辑注册到 Magento 的附加验证器列表中。
创建文件：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({}); } );
说明：
- uiComponent 是所有 UI 组件的基础。
- Magento_Checkout/js/model/payment/additional-validators 是 Magento 提供的用于管理支付步骤附加验证器的模块。
- Vendor_MyCheckoutValidator/js/model/final-address-check-validator 是我们实际的验证逻辑文件，将在下一步创建。
- additionalValidators.registerValidator(finalAddressCheckValidator) 这一行是关键，它将我们的验证逻辑注入到结账流程中。
步骤四：编写自定义验证逻辑
这是我们实现具体验证规则的地方。我们将在这个文件中获取输入字段的值并应用我们的验证逻辑。
创建文件：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 { /** * 验证方法，在结账提交时被调用 * @returns {boolean} 如果验证通过返回 true，否则返回 false */ validate: function () { var cityIsFine = true, city = $('input[name="city"]').val(); // 通过名称获取城市输入字段的值 // 示例验证规则：城市不能以 'Z' 开头 if (city.match(/^Z/)) { messageList.addErrorMessage({ message: $t('We are sorry, your city starts with a Z. Please choose another city.') }); cityIsFine = false; } // 可以添加更多验证规则，例如对街道字段 var street0 = $('input[name="street[0]"]').val(); // 获取街道字段 (通常第一个街道字段名为 street[0]) if (street0 && street0.length < 3) { messageList.addErrorMessage({ message: $t('Street address must be at least 3 characters long.') }); cityIsFine = false; // 如果有任何验证失败，都设为 false } // 打印到控制台进行调试 console.log('City:', city); console.log('Street[0]:', street0); if (!cityIsFine) { return false; // 验证失败 } return true; // 验证通过 } }; } );
说明：
- jquery 用于通过选择器获取 dom 元素的值。
- mage/translate ($t) 用于翻译错误消息。
- Magento_Ui/js/model/messageList 用于在前端显示错误消息给用户。
- validate 方法是核心，它必须返回 true（验证通过）或 false（验证失败）。
- 我们使用 $(‘input[name=”city”]’).val() 来获取城市输入字段的值。对于街道字段，通常使用 $(‘input[name=”street[0]”]’).val()。您可以通过浏览器开发者工具检查实际的 name 属性。
- 当验证失败时，messageList.addErrorMessage 会将错误消息显示在结账页的顶部。
扩展到街道字段
要为街道字段添加验证，只需在 final-address-check-validator.js 的 validate 方法中，使用相应的 name 属性来获取其值。例如，如果您的第一个街道字段的 name 属性是 street[0]，则可以使用 $(‘input[name=”street[0]”]’).val()。
注意事项与部署
完成上述代码后，您需要执行以下步骤以确保更改生效：
- 安装模块：
php bin/magento setup:upgrade
- 清除缓存：
php bin/magento cache:clean php bin/magento cache:flush
特别注意清除前端缓存。
- 部署静态文件：
php bin/magento setup:static-content:deploy -f
- 清除浏览器缓存： 彻底清除您的浏览器缓存，以确保加载最新的 JavaScript 文件。
现在，当您在结账页的支付步骤尝试输入一个以“Z”开头的城市（例如“Zenith”）并点击支付按钮时，应该会看到自定义的错误消息。
进一步探讨：自动补全功能的实现思路
虽然上述验证器机制非常适合执行验证逻辑，但它并非直接用于渲染用户界面元素（如自动补全建议列表）。要在 Magento 2 结账页实现城市和街道的自动补全功能，您需要采取不同的策略，主要集中在 UI 组件的定制上。
以下是几种可能的实现思路：
-
UI 组件覆盖或 Mixin：
- 覆盖 (Override)： 找到负责渲染城市/街道输入字段的原始 UI 组件及其 Knockout 模板。然后，在您的自定义模块中覆盖这些组件和模板。在覆盖后的组件中，您可以添加 keyup 事件监听器，当用户输入时发起 AJAX 请求获取建议列表，并动态地将这些建议渲染到输入框下方。
- Mixin (混合)： 这是一个更推荐的方法，因为它减少了对核心文件的直接修改。您可以创建一个 Mixin 来扩展现有的城市/街道 UI 组件的 JavaScript 逻辑。在 Mixin 中，您可以添加事件监听器、AJAX 请求逻辑以及处理建议列表的渲染。这通常需要更深入地理解 Magento UI 组件的生命周期和 Knockout.js 的数据绑定。
-
外部 JavaScript 监听与 DOM 操作：
- 类似于原问题中尝试的方法，您可以编写一个独立的 JavaScript 组件。这个组件不需要注册为附加验证器，而是可以在结账页加载完成后，通过 jQuery 或原生 JavaScript 监听城市/街道输入框的 keyup 事件。
- 当事件触发时，发起 AJAX 请求到后端获取建议数据。
- 收到数据后，动态创建 HTML 元素（例如 <ul> 列表）并将其插入到输入框下方的 DOM 中，显示建议。
- 同时，需要处理点击建议项时的逻辑，将选中的值填充到输入框中，并隐藏建议列表。
- 优势： 相对简单，不直接修改现有 UI 组件。
- 挑战： 需要手动管理 DOM 元素，可能与 Knockout 的数据绑定产生冲突，需要确保建议列表的样式和行为与 Magento 主题一致。
关于 AJAX 请求： 无论选择哪种自动补全实现方法，AJAX 请求都将在您的 JavaScript 文件中完成。您可以通过 Magento 的 urlBuilder 或直接在 JS 中构建 AJAX 请求的 URL。后端需要有一个自定义的控制器来处理这些 AJAX 请求，返回城市/街道的建议列表。关键在于，您无需在 .html 模板中嵌入 PHP 来获取 AJAX URL，因为 JavaScript 本身就可以构建或接收这些 URL。
总结
本教程详细介绍了如何在 Magento 2 结账页为城市和街道输入字段实现自定义验证。通过利用 Magento 的 UI 组件和附加验证器机制，我们能够以符合平台最佳实践的方式，添加复杂的验证逻辑，而无需直接修改核心模板或在其中嵌入 PHP 代码。对于自动补全功能，虽然验证器本身不直接负责 UI 渲染，但我们可以通过 UI 组件的覆盖/Mixin 或独立的 JavaScript 组件，结合 AJAX 请求，实现强大的用户体验。掌握这些技术，将使您能够更灵活地定制 Magento 2 的前端行为。
以上就是Magento 2 结账页城市与街道输入字段的自定义验证与自动补全实现教程的详细内容，更多请关注php中文网其它相关文章！