Yii Framework CJuiSelectable 可選取清單元件：多項選擇與視覺回饋

CJuiSelectable 封裝 jQuery UI Selectable，將清單項目變為可框選/點選的互動元素，支援單選/多選、鍵盤操作與選取事件回調。

基本用法：CSS 樣式與 Widget 配置

<?php
Yii::app()->clientScript->registerCss('selectable', "
    #selectable { list-style:none; margin:0; padding:0; width:60%; }
    #selectable li { margin:2px; padding:4px; border:1px solid #ddd; background:#f7f7f7; cursor:default; }
    #selectable .ui-selecting { border:1px solid #fad42e; background:#fff9e6; }
    #selectable .ui-selected { border:1px solid #fad42e; background:#fcefa1; font-weight:bold; }
    #select-result { margin:10px 0; padding:5px; background:#f0f0f0; }
", 'screen', CClientScript::POS_HEAD);
?>

<h2>可選取清單</h2>
<center id="select-result">未選取任何項目</center>

<?php $this->widget('zii.widgets.jui.CJuiSelectable', array(
    'id' => 'selectable',
    'items' => array(
        'id1' => '項目一：台北市',
        'id2' => '項目二：新北市',
        'id3' => '項目三：桃園市',
        'id4' => '項目四：台中市',
        'id5' => '項目五：高雄市',
    ),
    'options' => array(
        'filter' => 'li',           // 可選取的子元素
        'tolerance' => 'touch',     // 判定選取演算法
        'selected' => 'js:function(event, ui) {
            updateSelection();
        }',
        'unselected' => 'js:function(event, ui) {
            updateSelection();
        }',
        'stop' => 'js:function(event, ui) {
            updateSelection();
        }',
    ),
)); ?>

<script>
function updateSelection() {
    var selected = $("#selectable .ui-selected");
    var texts = selected.map(function() { return $(this).text(); }).get();
    $("#select-result").text(texts.length ? "已選取: " + texts.join(", ") : "未選取任何項目");
}
</script>

關鍵選項與事件

進階：表單整合與批次操作

<?php $form=$this->beginWidget('CActiveForm'); ?>
    <?php echo $form->hiddenField($model, 'selected_ids'); ?>
    <?php $this->widget('zii.widgets.jui.CJuiSelectable', array(
        'id' => 'user-selectable',
        'items' => CHtml::listData(User::model()->findAll(), 'id', 'username'),
        'options' => array(
            'stop' => 'js:function() {
                var ids = $("#user-selectable .ui-selected").map(function() { return this.id; }).get();
                $("#User_selected_ids").val(ids.join(","));
            }',
        ),
    )); ?>
    <?php echo CHtml::submitButton('批次刪除'); ?>
<?php $this->endWidget(); ?>

鍵盤操作支援

• Shift + Click：範圍選取
• Ctrl/Cmd + Click：切換單項選取狀態
• Ctrl/Cmd + A：全選（需額外 JS 綁定）
• 方向鍵移動焦點，Space 切換選取

注意事項

• 大量項目（>500）效能下降，建議分頁或虛擬滾動
• 行動裝置框選手勢與滑動衝突，建議改用點選模式或提供勾選框替代
• 無障礙：確保選取狀態有足夠色彩對比，螢幕閱讀器可識別
• 選取結果同步到隱藏欄位時，注意 id 屬性需為唯一識別碼