Yii2 GridView URL参数优化技巧

本教程旨在解决Yii2 GridView在使用自定义过滤器后，URL中出现大量空查询参数的问题。我们将通过覆盖并修改Yii2 GridView的JavaScript资源文件，并在应用配置中调整AssetManager，实现自动移除未填充的URL参数，从而优化URL的整洁性和可读性，避免直接修改vendor目录文件，确保项目维护性和升级的便利性。

引言：URL参数清理的重要性

在使用Yii2的GridView组件结合自定义过滤器时，我们经常会遇到一个问题：即使某些过滤器字段未填写，其对应的空参数仍然会出现在浏览器URL中，例如：localhost:20024/consignment?fid=&post_code=&pud2_mrn=&pud2_status=PUDP&pud_status=&...。这种包含大量空参数的URL不仅冗长、不美观，可能对用户体验造成影响，也可能在某些情况下对搜索引擎优化（SEO）或服务器日志分析带来不便。本教程将提供一种优雅的解决方案，通过修改Yii2 GridView的默认行为，在请求发送前自动移除这些无用的空参数。

核心解决方案：覆盖并修改GridView的JavaScript资产

Yii2 GridView的过滤逻辑主要由其前端JavaScript文件 yii.gridView.js 控制。为了实现参数清理，我们需要修改这个文件中的 applyFilter 方法。为了避免直接修改 vendor 目录下的核心文件（这会导致在Yii更新时被覆盖），我们将采取“覆盖”策略。

步骤一：复制并自定义 yii.gridView.js

首先，将Yii2核心库中的 yii.gridView.js 文件复制到您的项目 web 目录下的自定义位置，例如 web/js/custom。

源文件路径：vendor/yiisoft/yii2/assets/yii.gridView.js

目标路径示例：web/js/custom/yii.gridView.js

步骤二：修改 applyFilter 方法以移除空参数

打开您刚刚复制到 web/js/custom/yii.gridView.js 的文件。找到 applyFilter 方法。在该方法内部，您会找到一行类似 var pos = settings.filterUrl.indexOf('?'); 的代码。

在这行代码之前，插入以下JavaScript代码片段：

// ... 其他代码 ...

/**
 * Applies the filter to the grid.
 * @param {object} settings the grid filter settings.
 * @param {string} settings.filterUrl the URL to send the filter request to.
 * @param {string} settings.filterSelector the selector for the filter form.
 */
var applyFilter = function (settings) {
    var $form = $(settings.filterSelector);
    var data = $form.serializeArray();

    // --- 在此处插入代码以移除空参数 ---
    $.each(data, function (index, obj) {
        if (obj.value.length === 0) {
            data[index] = null; // 将空值的参数设置为null
        }
    });
    // 过滤掉所有null项
    data = $.grep(data, function(n){ return n !== null; });
    // --- 插入代码结束 ---

    var pos = settings.filterUrl.indexOf('?');
    var url = pos < 0 ? settings.filterUrl : settings.filterUrl.substring(0, pos);

    // ... 后续代码 ...
};

// ... 其他代码 ...

代码解释：

• $form.serializeArray() 会将表单数据序列化为一个对象数组，每个对象包含 name 和 value 属性。
• $.each(data, function (index, obj) { ... }) 遍历这个数组。
• if (obj.value.length === 0) 检查当前参数的值是否为空字符串。
• data[index] = null; 将值为空的参数项设置为 null。
• data = $.grep(data, function(n){ return n !== null; }); 这一行至关重要，它会从 data 数组中移除所有值为 null 的项，从而有效地删除了空参数。

步骤三：配置 AssetManager 使用自定义文件

最后一步是告诉Yii2您的应用程序应该使用您自定义的 yii.gridView.js 文件，而不是Yii核心库中的默认文件。这通过修改您的应用程序配置文件（通常是 config/web.php 或 config/main.php）中的 assetManager 组件来完成。

在您的配置文件中找到 components 数组，并添加或修改 assetManager 配置，如下所示：

return [
    // ... 其他配置 ...
    'components' => [
        // ... 其他组件配置 ...
        'assetManager' => [
            'bundles' => [
                'yii\grid\GridViewAsset' => [
                    'sourcePath' => '@webroot/js/custom', // 指向您自定义js文件的目录
                    'basePath' => '@webroot/js/custom',   // 同上
                    'baseUrl' => '@web/js/custom',        // 通过web访问的URL路径
                    'js' => [
                        'yii.gridView.js',                // 指定自定义的js文件名
                    ],
                ],
            ],
        ],
        // ... 其他组件配置 ...
    ],
    // ... 其他配置 ...
];

配置解释：

• 'yii\grid\GridViewAsset'：这是Yii2 GridView组件使用的资产包的类名。我们通过配置这个类来覆盖其默认行为。
• 'sourcePath' 和 'basePath'：这两个参数告诉AssetManager您的自定义JavaScript文件的物理路径。@webroot 是Yii2的路径别名，指向应用程序的 web 目录。
• 'baseUrl'：这个参数定义了通过Web服务器访问这些资产的URL路径。@web 也是Yii2的路径别名，代表Web根目录的URL。
• 'js'：这个数组指定了要加载的JavaScript文件。在这里，我们指向了我们自定义的 yii.gridView.js。

重要提示： 请确保 sourcePath、basePath 和 baseUrl 中的路径与您实际存放 yii.gridView.js 文件的位置和Web可访问路径相匹配。

总结与注意事项

通过以上三个步骤，您已经成功地修改了Yii2 GridView的行为，使其在提交过滤器时自动移除URL中的空查询参数。

优点：

• URL整洁： 显著改善URL的可读性和美观性。
• 避免修改核心文件： 通过AssetManager的覆盖机制，我们避免了直接修改 vendor 目录下的文件，确保了项目的可维护性和Yii2框架升级的顺畅。
• 服务器负载优化： 减少了不必要的参数传输，虽然影响微小，但在高并发场景下仍有积极意义。

注意事项：

• 路径准确性： 务必仔细检查 assetManager 配置中的路径是否正确指向您自定义的JavaScript文件。任何路径错误都可能导致自定义文件未被加载，或者应用程序无法正常工作。
• 兼容性： 本教程基于Yii2的默认GridView实现。如果您使用了第三方Grid组件或对GridView进行了深度定制，可能需要根据实际情况调整修改方案。
• 前端框架冲突： 确保您的自定义JavaScript代码与项目中使用的其他前端库（如jQuery）没有版本或语法上的冲突。

通过本教程，您不仅解决了Yii2 GridView URL参数冗余的问题，也学习了如何安全地覆盖Yii2核心组件的默认行为，这对于构建健壮和可维护的Yii2应用程序至关重要。