Magento 2 结账页城市与街道自定义验证指南_石家庄创泽智能科技有限公司

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

Magento 2 结账页城市与街道自定义验证指南

2025-11-08

浏览次数：次

返回列表

magento 2 结账页城市与街道自定义验证指南

本教程详细介绍了如何在 Magento 2 结账流程中为城市和街道字段实现自定义验证。我们将通过创建一个自定义模块，利用 Magento 2 的 UI 组件和附加验证器机制，在不直接修改 Knockout HTML 模板的情况下，实现对用户输入地址信息的有效校验，并展示如何获取字段值及显示错误信息。

Magento 2 结账验证机制概述

在 Magento 2 中，结账页面大量使用了 Knockout.js 框架进行动态渲染。这意味着前端模板（.html 文件）是纯客户端渲染的，无法直接嵌入 PHP 代码来生成动态 URL 或执行服务器端逻辑。如果需要进行自定义验证，特别是涉及服务器端数据（如城市列表）的验证，我们不能像传统 PHP 模板那样直接在 .html 文件中混合 PHP 和 J*aScript。

Magento 2 提供了一种更优雅且可扩展的方式来处理结账流程中的验证：附加验证器 (additional validators)。通过这种机制，我们可以在结账步骤（例如支付信息步骤）注册自定义的 J*aScript 验证逻辑，这些逻辑会在用户尝试进入下一步或提交订单时被触发。这种方法避免了直接修改核心模板，保证了代码的健壮性和可维护性。

创建自定义验证模块

首先，我们需要创建一个 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 方法将其注册到系统中。

易标AI

告别低效手工，迎接AI标书新时代！3分钟智能生成，行业唯一具备查重功能，自动避雷废标项

135 查看详情易标AI

编写核心验证逻辑

现在，我们来创建包含实际验证规则的 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 (在开发模式下可能需要，生产模式下必须)。
清除浏览器缓存: 确保浏览器加载的是最新的 J*aScript 文件。

现在，访问你的 Magento 2 商店结账页面。在支付信息步骤填写地址时，尝试输入一个以 'Z' 开头的城市（例如 "Zenith"）。当你点击“继续支付”或类似按钮时，如果城市以 'Z' 开头，系统将显示错误消息，并且无法继续。