# select2

**Repository Path**: fastadmin_2/select2

## Basic Information

- **Project Name**: select2
- **Description**: select2 插件
- **Primary Language**: PHP
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-14
- **Last Updated**: 2026-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Select2 下拉框美化插件

FastAdmin 的 Select2 下拉框美化插件，用于将系统原生下拉框替换为功能更强大、样式更美观的 Select2 下拉框。

---

## 目录结构

```
addons/select2/
├── css/                          # 样式文件目录
│   ├── select2.bootstrap.css     # Bootstrap 主题样式
│   └── select2.min.css           # Select2 核心样式
├── js/                           # JavaScript 文件目录
│   ├── i18n/                     # 国际化语言包
│   │   └── zh-CN.js              # 简体中文语言包
│   └── select2.full.min.js       # Select2 完整版（含所有功能）
├── .addonrc                      # 插件配置文件
├── Select2.php                   # 插件主类文件
├── bootstrap.js                  # 插件初始化脚本
├── config.php                    # 插件后台配置
├── info.ini                      # 插件信息配置
└── readme.md                     # 本说明文件
```

---

## 更新说明

### 版本 1.0.0

**发布日期**: 2026-04-14

**更新内容**:
- 初始版本发布
- 集成 Select2 4.1.0 完整版
- 支持自动替换系统所有原生下拉框
- 支持自定义选择器配置
- 支持中文语言包
- 支持 Bootstrap 主题样式
- 支持允许清空选择功能
- 支持占位提示文字

**功能特性**:
- 自动检测并跳过已初始化的元素
- 支持通过 `data-no-select2="true"` 排除特定下拉框
- 自动销毁 Bootstrap Select 避免冲突
- 宽度自适应父容器

---

## 二次开发说明

### 1. 插件架构

本插件基于 FastAdmin 的插件机制开发，主要包含以下核心文件：

#### 1.1 主类文件 (Select2.php)

```php
namespace addons\select2;

use think\Addons;

class Select2 extends Addons
{
    // 安装/卸载/启用/禁用钩子
    public function install() { return true; }
    public function uninstall() { return true; }
    public function enable() { return true; }
    public function disable() { return true; }
    
    // 配置初始化钩子 - 将配置传递到前端
    public function configInit(&$params)
    {
        $config = $this->getConfig();
        $params['select2'] = [
            'enabled' => isset($config['autoreplace']) && $config['autoreplace'] === '开启',
            'selector' => $config['selector'] ?? 'select',
        ];
    }
}
```

#### 1.2 初始化脚本 (bootstrap.js)

通过重写 `Form.events.bindevent` 方法，在表单绑定事件时自动初始化 Select2。

### 2. 扩展开发指南

#### 2.1 添加新的配置项

在 `config.php` 中添加新的配置：

```php
return [
    [
        'name' => 'theme',
        'title' => '主题样式',
        'type' => 'radio',
        'content' => [
            'default' => '默认',
            'classic' => '经典',
        ],
        'value' => 'default',
        'rule' => 'required',
        'tip' => '选择 Select2 的主题样式',
    ],
];
```

然后在 `Select2.php` 的 `configInit` 方法中传递新配置：

```php
public function configInit(&$params)
{
    $config = $this->getConfig();
    $params['select2'] = [
        'enabled' => isset($config['autoreplace']) && $config['autoreplace'] === '开启',
        'selector' => $config['selector'] ?? 'select',
        'theme' => $config['theme'] ?? 'default',  // 新增配置
    ];
}
```

最后在 `bootstrap.js` 中使用新配置：

```javascript
$this.select2({
    language: 'zh-CN',
    width: '100%',
    theme: Config.select2.theme || 'default',  // 使用新配置
    allowClear: true,
    placeholder: '请选择'
});
```

#### 2.2 添加新的语言包

1. 在 `js/i18n/` 目录下添加新的语言文件，如 `en.js`
2. 在 `bootstrap.js` 中配置 RequireJS 路径：

```javascript
require.config({
    paths: {
        'select2': '../addons/select2/js/select2.full.min',
        'select2-zh': '../addons/select2/js/i18n/zh-CN',
        'select2-en': '../addons/select2/js/i18n/en',  // 新增语言包
    },
    // ...
});
```

#### 2.3 自定义初始化逻辑

如需在特定页面或特定条件下使用不同的初始化配置，可以：

```javascript
// 在页面脚本中覆盖默认配置
require(['select2', 'select2-zh'], function () {
    $('#my-custom-select').select2({
        language: 'zh-CN',
        width: 'resolve',
        allowClear: false,
        placeholder: '请选择一个选项',
        minimumResultsForSearch: 10,  // 超过10个选项才显示搜索框
        maximumSelectionLength: 3,     // 最多选择3项
    });
});
```

#### 2.4 添加 AJAX 数据源支持

```javascript
$('#ajax-select').select2({
    language: 'zh-CN',
    width: '100%',
    ajax: {
        url: '/api/category/select',
        dataType: 'json',
        delay: 250,
        data: function (params) {
            return {
                q: params.term,  // 搜索关键词
                page: params.page
            };
        },
        processResults: function (data, params) {
            params.page = params.page || 1;
            return {
                results: data.data,
                pagination: {
                    more: (params.page * 10) < data.total
                }
            };
        },
        cache: true
    },
    placeholder: '搜索并选择',
    minimumInputLength: 1,  // 至少输入1个字符才搜索
});
```

### 3. 常用配置项说明

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `language` | string | 'zh-CN' | 语言包 |
| `width` | string | '100%' | 宽度，可设置为 'resolve'、'element' 或具体像素值 |
| `theme` | string | 'default' | 主题样式 |
| `allowClear` | boolean | true | 是否允许清空选择 |
| `placeholder` | string | '请选择' | 占位提示文字 |
| `minimumResultsForSearch` | number | 0 | 至少多少选项才显示搜索框，Infinity 表示永不显示 |
| `maximumSelectionLength` | number | 0 | 最多选择几项，0 表示无限制 |
| `minimumInputLength` | number | 0 | AJAX 模式下至少输入多少字符才搜索 |
| `closeOnSelect` | boolean | true | 选择后是否关闭下拉框 |
| `dropdownParent` | jQuery | null | 下拉框的父元素，用于解决模态框中的定位问题 |

### 4. 事件处理

```javascript
// 选择改变事件
$('#my-select').on('select2:select', function (e) {
    var data = e.params.data;
    console.log('选中:', data.id, data.text);
});

// 取消选择事件
$('#my-select').on('select2:unselect', function (e) {
    var data = e.params.data;
    console.log('取消:', data.id, data.text);
});

// 打开下拉框事件
$('#my-select').on('select2:open', function (e) {
    console.log('下拉框已打开');
});

// 关闭下拉框事件
$('#my-select').on('select2:close', function (e) {
    console.log('下拉框已关闭');
});
```

### 5. 方法调用

```javascript
// 获取/设置选中值
var value = $('#my-select').val();
$('#my-select').val('2').trigger('change');

// 销毁 Select2 实例
$('#my-select').select2('destroy');

// 打开/关闭下拉框
$('#my-select').select2('open');
$('#my-select').select2('close');

// 动态添加选项
var newOption = new Option('新选项', 'new-value', false, false);
$('#my-select').append(newOption).trigger('change');

// 清空所有选项
$('#my-select').empty().trigger('change');
```

### 6. 注意事项

1. **避免重复初始化**: 插件会自动检测 `select2-hidden-accessible` 类来跳过已初始化的元素
2. **排除特定元素**: 在 HTML 中添加 `data-no-select2="true"` 可排除特定下拉框
3. **Bootstrap Select 冲突**: 插件会自动销毁 Bootstrap Select 实例
4. **模态框中使用**: 如果在模态框中使用，建议设置 `dropdownParent` 选项：
   ```javascript
   $('#modal-select').select2({
       dropdownParent: $('#my-modal')
   });
   ```

### 7. 调试技巧

在 `bootstrap.js` 中已添加控制台输出，可在浏览器开发者工具中查看插件加载状态：

```javascript
console.log('select2 插件加载成功');
console.log($this);  // 输出当前处理的元素
```

---

## 参考链接

- [Select2 官方文档](https://select2.org/)
- [FastAdmin 插件开发文档](https://doc.fastadmin.net/docs/addons.html)
- [Select2 GitHub 仓库](https://github.com/select2/select2)