README

为 Yii 框架 2.0 提供的双列表框。

描述

softark\duallistbox\DualListbox 小部件是 Bootstrap 双列表框 的 Yii 2 封装。

它与 bootstrap 3, 4 或 5 兼容

要求

• Yii 版本 2.0.0 或更高
• yii2-bootstrap, yii2-bootstrap4 或 yii2-bootstrap5
• istvan-ujjmeszaros/bootstrap-duallistbox v.3.0.x 或 v.4.0.x

使用方法

1. 在您的项目的 composer.json 中添加 softark/yii2-dual-listbox 和 istvan-ujjmeszaros/bootstrap-duallistbox，然后让 Composer 配置您的项目。

   • 您必须根据 bootstrap 的版本使用 istvan-ujjmeszaros/bootstrap-duallistbox 的不同版本。
   • 对于 bootstrap 3，使用 ~3.0.0

   "require": {
       "php": ">=7.0.0",
       "yiisoft/yii2": "*",
       "yiisoft/yii2-bootstrap": "*",
       "istvan-ujjmeszaros/bootstrap-duallistbox": "~3.0.0",
       "softark/yii2-dual-listbox": "dev-master"
   },

   • 对于 bootstrap 4 和 5，使用 ~4.0.0

   "require": {
       "php": ">=7.0.0",
       "yiisoft/yii2": "*",
       "yiisoft/yii2-bootstrap4": "*", // OR
       "yiisoft/yii2-bootstrap5": "*",
       "istvan-ujjmeszaros/bootstrap-duallistbox": "~4.0.0",
       "softark/yii2-dual-listbox": "dev-master"
   },

2. 在您的视图中使用 softark\duallistbox\DualListbox::widget() 来代替 yii\helpers\Html::listBox()、yii\helpers\Html::activeListBox() 或 yii\widgets\ActiveField::listBox()。

   1. 使用 name 和 selection 替换 Html::listBox()

      use softark\duallistbox\DualListbox;
      ...
      <?php
          $options = [
              'multiple' => true,
              'size' => 20,
          ];
          // echo Html::listBox($name, $selection, $items, $options);
          echo DualListbox::widget([
              'name' => $name,
              'selection' => $selection,
              'items' => $items,
              'options' => $options,
              'clientOptions' => [
                  'moveOnSelect' => false,
                  'selectedListLabel' => 'Selected Items',
                  'nonSelectedListLabel' => 'Available Items',
              ],
          ]);
      ?>

   2. 使用 model 和 attribute 替换 Html::activeListBox()

      use softark\duallistbox\DualListbox;
      ...
      <?php
          $options = [
              'multiple' => true,
              'size' => 20,
          ];
          // echo Html::activeListBox($model, $attribute, $items, $options);
          echo DualListbox::widget([
              'model' => $model,
              'attribute' => $attribute,
              'items' => $items,
              'options' => $options,
              'clientOptions' => [
                  'moveOnSelect' => false,
                  'selectedListLabel' => 'Selected Items',
                  'nonSelectedListLabel' => 'Available Items',
              ],
          ]);
      ?>

   3. 使用 model 和 attribute 替换 ActiveField::listBox()

      use softark\duallistbox\DualListbox;
      ...
      <?php
          $options = [
              'multiple' => true,
              'size' => 20,
          ];
          // echo $form->field($model, $attribute)->listBox($items, $options);
          echo $form->field($model, $attribute)->widget(DualListbox::className(),[
              'items' => $items,
              'options' => $options,
              'clientOptions' => [
                  'moveOnSelect' => false,
                  'selectedListLabel' => 'Selected Items',
                  'nonSelectedListLabel' => 'Available Items',
              ],
          ]);
      ?>

3. 在服务器端收集用户输入，就像使用具有多个选择的单列表框一样。请注意，输入值将是一个数组。

   如果您在处理用户输入时遇到困难，请阅读 示例代码，它演示了如何使用双列表框处理以数组格式存储的数据。

softark\duallistbox\DualListbox 的属性

1. name @var string

   输入名称。

2. selection @var array

   选定的值。

3. model @var yii\base\Model

   模型对象。

4. attribute @var string

   属性名称。

5. items @var array

   选项数据项。数组键是选项值，数组值是对应的选项标签。

6. options @var array

   列表框的标签选项，以键值对的形式。

7. clientOptions @var array

   Bootstrap 双列表框的选项，以键值对的形式。有关详细信息，请参阅 初始化参数对象 部分，这是 Bootstrap 双列表框 的官方文档。

前 6 个属性对应于在 Html::listBox()、Html::activeListBox() 和 ActiveField::listBox() 中使用的参数。

请注意，您必须使用 name-selection 对或 model-attribute 对。前者用于替换 Html::listBox()，后者用于 Html::activeListBox() 和 ActiveField::listBox()。

注意

由于某些原因，Bootstrap 双列表框 在移动设备浏览器中无法正常工作，因此您不能为这些设备使用此小部件。

考虑使用复选框列表。

历史记录

• 版本 1.0.0 (2016-01-12)
  • 在 Yii 2.0.6 上进行测试
• 版本 1.0.1 (2020-09-18)
  • 支持 bootstrap3 和 bootstrap4
• 版本 1.0.2 (2022-09-08)
  • 同时支持 bootstrap5