Выбираемый виджет

Выбираемый виджетверсия добавлена: 1.0

Описание: Используйте мышь для выбора элементов, по одному или группами.

Быстрое навигацияПримеры

Плагин jQuery UI Selectable позволяет выбирать элементы, перетаскивая рамку (иногда называемую лассо) мышью по элементам. Элементы также можно выбирать щелчком или перетаскиванием, удерживая клавиши Ctrl/Meta, что позволяет осуществлять множественный (несмежный) выбор.

Темы

Виджет selectable использует фреймворк CSS jQuery UI CSS для стилизации своего внешнего вида. Если требуется специфическая стилизация selectable, следующие имена классов CSS можно использовать для перезаписи или в качестве ключей для classes параметра:

ui-selectable: Элемент, подлежащий выбору.
- ui-selectee: Один из выбираемых элементов, как указано в filter параметре. Этот элемент также может получить один из следующих классов: ui-selecting (когда элемент входит в рамку), ui-selected (после успешного выбора), ui-unselecting (когда элемент больше не входит в рамку).
ui-selectable-helper: Элемент "рамки" для визуализации текущего выбора.

Зависимости

Дополнительные замечания:

Этот виджет требует функционального CSS, иначе он не будет работать. При создании пользовательской темы используйте файл CSS виджета в качестве отправной точки.

Параметры

appendTo

Тип: Селектор

Значение по умолчанию: "body"

Элемент, к которому должен быть добавлен помощник выбора (рамка).

Примеры кода:

Инициализируйте виджет selectable, указав параметр appendTo:

$( ".selector" ).selectable({
  appendTo: "#someElem"
});

Получите или установите параметр appendTo после инициализации:

// Getter
var appendTo = $( ".selector" ).selectable( "option", "appendTo" );
 
// Setter
$( ".selector" ).selectable( "option", "appendTo", "#someElem" );

autoRefresh

Тип: Boolean

Значение по умолчанию: true

Определяет, следует ли обновлять (пересчитывать) положение и размер каждого выбираемого элемента в начале каждой операции выбора. Если у вас много элементов, вы можете установить это значение в false и вызвать метод refresh() вручную.

Примеры кода:

Инициализируйте виджет selectable, указав параметр autoRefresh:

$( ".selector" ).selectable({
  autoRefresh: false
});

Получите или установите параметр autoRefresh после инициализации:

// Getter
var autoRefresh = $( ".selector" ).selectable( "option", "autoRefresh" );
 
// Setter
$( ".selector" ).selectable( "option", "autoRefresh", false );

cancel

Тип: Селектор

Значение по умолчанию: "input,textarea,button,select,option"

Препятствует выбору, если вы начинаете на элементах, соответствующих селектору.

Примеры кода:

Инициализируйте виджет selectable, указав параметр cancel:

$( ".selector" ).selectable({
  cancel: "a,.cancel"
});

Получите или установите параметр cancel после инициализации:

// Getter
var cancel = $( ".selector" ).selectable( "option", "cancel" );
 
// Setter
$( ".selector" ).selectable( "option", "cancel", "a,.cancel" );

classes

Тип: Объект

Значение по умолчанию: {}

Укажите дополнительные классы для добавления к элементам виджета. Любые классы, указанные в разделе Темы, можно использовать в качестве ключей для их перезаписи. Подробнее об этом параметре можно узнать в статье об этом параметре classes.

Примеры кода:

Инициализируйте виджет selectable, указав параметр classes, изменяя тему для класса ui-selectable:

$( ".selector" ).selectable({
  classes: {
    "ui-selectable": "highlight"
  }
});

Получите или установите свойство параметра classes после инициализации, здесь читаем и изменяем тему для класса ui-selectable:

// Getter
var themeClass = $( ".selector" ).selectable( "option", "classes.ui-selectable" );
 
// Setter
$( ".selector" ).selectable( "option", "classes.ui-selectable", "highlight" );

delay

Тип: Целое число

Значение по умолчанию: 0

Время в миллисекундах, определяющее, когда должен начаться выбор. Это помогает предотвратить нежелательные выделения при нажатии на элемент. (версия устаревшая: 1.12)

Примеры кода:

Инициализируйте виджет selectable, указав параметр delay:

$( ".selector" ).selectable({
  delay: 150
});

Получите или установите параметр delay после инициализации:

// Getter
var delay = $( ".selector" ).selectable( "option", "delay" );
 
// Setter
$( ".selector" ).selectable( "option", "delay", 150 );

disabled

Тип: Boolean

Значение по умолчанию: false

Отключает виджет selectable, если значение равно true.

Примеры кода:

Инициализируйте виджет selectable, указав параметр disabled:

$( ".selector" ).selectable({
  disabled: true
});

Получите или установите параметр disabled после инициализации:

// Getter
var disabled = $( ".selector" ).selectable( "option", "disabled" );
 
// Setter
$( ".selector" ).selectable( "option", "disabled", true );

distance

Тип: Число

Значение по умолчанию: 0

Допуск в пикселях, для начала выбора. Если указано, выбор не начнется, пока мышь не будет перетащена на указанное расстояние. (версия устаревшая: 1.12)

Примеры кода:

Инициализируйте виджет selectable, указав параметр distance:

$( ".selector" ).selectable({
  distance: 30
});

Получите или установите параметр distance после инициализации:

// Getter
var distance = $( ".selector" ).selectable( "option", "distance" );
 
// Setter
$( ".selector" ).selectable( "option", "distance", 30 );

filter

Тип: Селектор

Значение по умолчанию: "*"

Соответствующие дочерние элементы будут выбираемыми.

Примеры кода:

Инициализируйте виджет selectable, указав параметр filter:

$( ".selector" ).selectable({
  filter: "li"
});

Получите или установите параметр filter после инициализации:

// Getter
var filter = $( ".selector" ).selectable( "option", "filter" );
 
// Setter
$( ".selector" ).selectable( "option", "filter", "li" );

tolerance

Тип: Строка

Значение по умолчанию: "touch"

Указывает режим проверки, должен ли элемент быть выбран лассо. Возможные значения:

"fit": Лассо полностью перекрывает элемент.
"touch": Лассо перекрывает элемент любым образом.

Примеры кода:

Инициализируйте виджет selectable, указав параметр tolerance:

$( ".selector" ).selectable({
  tolerance: "fit"
});

Получите или установите параметр tolerance после инициализации:

// Getter
var tolerance = $( ".selector" ).selectable( "option", "tolerance" );
 
// Setter
$( ".selector" ).selectable( "option", "tolerance", "fit" );

Методы

destroy()Возвращает: jQuery (только для плагина)

Полностью удаляет функциональность выбора. Это вернёт элемент в состояние до инициализации.

Этот метод не принимает аргументы.

Примеры кода:

Вызов метода destroy:

$( ".selector" ).selectable( "destroy" );

disable()Возвращает: jQuery (только для плагина)

Отключает режим выбора.

Этот метод не принимает аргументы.

Примеры кода:

Вызов метода disable:

$( ".selector" ).selectable( "disable" );

enable()Возвращает: jQuery (только для плагина)

Включает режим выбора.

Этот метод не принимает аргументы.

Примеры кода:

Вызов метода enable:

$( ".selector" ).selectable( "enable" );

instance()Возвращает: Объект

Получает объект экземпляра выбора. Если у элемента нет связанного экземпляра, undefined возвращается.

В отличие от других методов виджетов, instance() безопасно вызывать для любого элемента после загрузки плагина выбора.

Этот метод не принимает аргументы.

Примеры кода:

Вызов метода instance:

$( ".selector" ).selectable( "instance" );

option( optionName )Возвращает: Объект

Получает значение, в настоящее время связанное со специфицированным optionName.

Примечание: Для опций, имеющих объекты в качестве значения, можно получить значение определённого ключа, используя нотацию с точкой. Например, "foo.bar" получит значение свойства bar в опции foo.

optionName

Тип: Строка

Имя опции для получения.

Примеры кода:

Вызов метода:

var isDisabled = $( ".selector" ).selectable( "option", "disabled" );

option()Возвращает: Простой объект

Получает объект, содержащий пары ключ/значение, представляющие текущий хеш опций выбора.

Этот метод не принимает аргументы.

Примеры кода:

Вызов метода:

var options = $( ".selector" ).selectable( "option" );

option( optionName, value )Возвращает: jQuery (только для плагина)

Устанавливает значение опции выбора, связанной с указанным optionName.

Примечание: Для опций, имеющих объекты в качестве значения, можно установить значение только одного свойства, используя нотацию с точкой для optionName. Например, "foo.bar" обновит только свойство bar опции foo.

optionName

Тип: Строка

Имя опции для установки.
value

Тип: Объект

Значение для установки опции.

Примеры кода:

Вызов метода:

$( ".selector" ).selectable( "option", "disabled", true );

option( options )Возвращает: jQuery (только для плагина)

Устанавливает одну или несколько опций для выбора.

options

Тип: Объект

Карта пар опция-значение для установки.

Примеры кода:

Вызов метода:

$( ".selector" ).selectable( "option", { disabled: true } );

refresh()Возвращает: jQuery (только для плагина)

Обновляет положение и размер каждого элемента выбора. Этот метод можно использовать для ручного перерасчёта положения и размера каждого элемента выбора, когда опция autoRefresh установлена в false.

Этот метод не принимает аргументы.

Примеры кода:

Вызов метода refresh:

$( ".selector" ).selectable( "refresh" );

События

create( event, ui )Тип: `selectablecreate`

Срабатывает при создании объекта selectable.

event

Тип: Event
ui

Тип: Объект

Примечание: Объект ui пустой, но включен для согласованности с другими событиями.

Примеры кода:

Инициализируйте selectable с указанным обратным вызовом create:

$( ".selector" ).selectable({
  create: function( event, ui ) {}
});

Свяжите обработчик событий с событием selectablecreate:

$( ".selector" ).on( "selectablecreate", function( event, ui ) {} );

selected( event, ui )Тип: `selectableselected`

Срабатывает в конце операции выбора, для каждого элемента, добавленного в выбор.

event

Тип: Event
ui

Тип: Объект
- selected
  
  Тип: Элемент
  
  Элемент selectable, который был выбран.

Примеры кода:

Инициализируйте selectable с указанным обратным вызовом selected:

$( ".selector" ).selectable({
  selected: function( event, ui ) {}
});

Свяжите обработчик событий с событием selectableselected:

$( ".selector" ).on( "selectableselected", function( event, ui ) {} );

selecting( event, ui )Тип: `selectableselecting`

Срабатывает во время операции выбора, для каждого элемента, добавляемого в выбор.

event

Тип: Event
ui

Тип: Объект
- selecting
  
  Тип: Элемент
  
  Текущий элемент selectable, который выбирается.

Примеры кода:

Инициализируйте selectable с указанным обратным вызовом selecting:

$( ".selector" ).selectable({
  selecting: function( event, ui ) {}
});

Свяжите обработчик событий с событием selectableselecting:

$( ".selector" ).on( "selectableselecting", function( event, ui ) {} );

start( event, ui )Тип: `selectablestart`

Срабатывает в начале операции выбора.

event

Тип: Event
ui

Тип: Объект

Примечание: Объект ui пустой, но включен для согласованности с другими событиями.

Примеры кода:

Инициализируйте selectable с указанным обратным вызовом start:

$( ".selector" ).selectable({
  start: function( event, ui ) {}
});

Свяжите обработчик событий с событием selectablestart:

$( ".selector" ).on( "selectablestart", function( event, ui ) {} );

stop( event, ui )Тип: `selectablestop`

Срабатывает в конце операции выбора.

event

Тип: Event
ui

Тип: Объект

Примечание: Объект ui пустой, но включен для согласованности с другими событиями.

Примеры кода:

Инициализируйте selectable с указанным обратным вызовом stop:

$( ".selector" ).selectable({
  stop: function( event, ui ) {}
});

Свяжите обработчик событий с событием selectablestop:

$( ".selector" ).on( "selectablestop", function( event, ui ) {} );

unselected( event, ui )Тип: `selectableunselected`

Срабатывает в конце операции выбора, для каждого элемента, удаленного из выбора.

event

Тип: Event
ui

Тип: Объект
- unselected
  
  Тип: Элемент
  
  Элемент selectable, который был снят с выбора.

Примеры кода:

Инициализируйте selectable с указанным обратным вызовом unselected:

$( ".selector" ).selectable({
  unselected: function( event, ui ) {}
});

Свяжите обработчик событий с событием selectableunselected:

$( ".selector" ).on( "selectableunselected", function( event, ui ) {} );

unselecting( event, ui )Тип: `selectableunselecting`

Срабатывает во время операции выбора, для каждого элемента, удаляемого из выбора.

event

Тип: Event
ui

Тип: Объект
- unselecting
  
  Тип: Элемент
  
  Текущий элемент selectable, который снимается с выбора.

Примеры кода:

Инициализируйте selectable с указанным обратным вызовом unselecting:

$( ".selector" ).selectable({
  unselecting: function( event, ui ) {}
});

Свяжите обработчик событий с событием selectableunselecting:

$( ".selector" ).on( "selectableunselecting", function( event, ui ) {} );

Пример:

Простой jQuery UI Selectable.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>selectable demo</title>
  <link rel="stylesheet" href="https://code.jquery.com/ui/1.13.3/themes/smoothness/jquery-ui.css">
  <style>
  #selectable .ui-selecting {
    background: #ccc;
  }
  #selectable .ui-selected {
    background: #999;
  }
  </style>
  <script src="https://code.jquery.com/jquery-3.7.1.js"></script>
  <script src="https://code.jquery.com/ui/1.13.3/jquery-ui.js"></script>
</head>
<body>
 
<ul id="selectable">
  <li>Item 1</li>
  <li>Item 2</li>
  <li>Item 3</li>
  <li>Item 4</li>
  <li>Item 5</li>
</ul>
 
<script>
$( "#selectable" ).selectable();
</script>
 
</body>
</html>

Выбираемый виджет