如何在CakePHP 3.8中使用Select2 Ajax实现自动补全下拉列表

现有代码核心问题 #

• 控制器模糊查询语法错误：直接写['task_id' => '%' . $term . '%']会被框架解析为精确匹配%xxx%字符串，不会触发模糊查询
• 缺少参数非空校验，q参数不存在时会抛出notice级错误
• 直接echo输出JSON不符合CakePHP响应规范，易引发额外输出导致JSON解析失败
• 缺少AJAX请求校验，普通访问也能触发接口

修复后的完整代码 #

1. 控制器层（VScriptsController.php） #

首先确认控制器顶部引入了必要的依赖类：

use Cake\ORM\TableRegistry;
use Cake\Http\Exception\BadRequestException;

修改searchTask方法代码：

public function searchTask()
{
    // 仅允许AJAX请求访问
    if (!$this->request->is('ajax')) {
        throw new BadRequestException(__('非法请求'));
    }
    // 安全获取查询参数，为空直接返回空数组
    $term = trim($this->request->getQuery('q', ''));
    if ($term === '') {
        return $this->response->withType('application/json')
            ->withStringBody(json_encode([]));
    }

    $tasksTable = TableRegistry::getTableLocator()->get('Tasks');
    $tasks = $tasksTable
        ->find()
        // 直接别名成select2要求的id、text字段，省去后续循环拼装
        ->select([
            'id' => 'task_id',
            'text' => 'task_id'
        ])
        // 加LIKE关键字才会触发模糊查询
        ->where(['task_id LIKE' => "%{$term}%"])
        ->limit(10)
        ->order(['task_id' => 'ASC'])
        ->toArray();

    // 按框架规范返回JSON响应，无需手动关闭autoRender
    return $this->response->withType('application/json')
        ->withStringBody(json_encode($tasks));
}

如果项目开启了Auth权限校验，需要在控制器的initialize方法中放开接口访问权限：

public function initialize()
{
    parent::initialize();
    // 无需登录即可访问则加这行，需登录访问可忽略
    $this->Auth->allow(['searchTask']);
}

2. 视图层 #

首先确认页面已提前引入jQuery、Select2的CSS和JS依赖，再初始化组件：

// 等待DOM加载完成后再初始化，避免元素未渲染导致初始化失败
$(function() {
    $('.js-data-example-ajax').select2({
        ajax: {
            url: "<?php echo Router::url(["controller"=>"VScripts","action"=>"searchTask"]); ?>",
            dataType: "json",
            delay: 250,
            data: function (params) {
                return {
                    q: params.term,
                };
            },
            processResults: function (data) {
                return {
                    results: data,
                };
            },
            cache: true
        },
        placeholder: '至少输入1个字符开始搜索',
        minimumInputLength: 1
    });
});

验证步骤 #

• 输入1个字符触发请求，打开浏览器控制台Network标签查看接口返回的JSON格式是否符合要求
• 确认查询结果匹配输入的关键词，下拉列表正常渲染

内容的提问来源于stack exchange，提问作者user17260425