Spec-Zone.ru › jQuery UI

Виджет Selectmenu

Виджет Selectmenuверсия добавлена: 1.11

Описание: Дублирует и расширяет функциональность стандартного HTML-элемента select, чтобы преодолеть ограничения стандартного элемента управления.

Быстрый переходПримеры

Параметры

appendTo
classes
disabled
icons
position
width

Методы

close
destroy
disable
enable
instance
menuWidget
open
option
refresh
widget

Точки расширения

_renderButtonItem
_renderItem
_renderMenu
_resizeMenu

События

change
close
create
focus
open
select

Selectmenu преобразует элемент <select> в стилизуемый и настраиваемый элемент управления. Виджет действует как прокси к исходному <select>; поэтому состояние исходного элемента сохраняется для отправки формы и сериализации.

Selectmenu поддерживает <optgroup> элементы и пользовательскую разметку для отображения таких представлений, как несколько строк. Виджет <select> и его параметры могут быть отключены добавлением атрибута disabled.

Примечание: Поддержка accesskey для пользовательских элементов в браузерах крайне ограничена. Поэтому, если атрибут accesskey присутствует в элементе <select>, он не будет работать с пользовательским selectmenu. Если атрибут accesskey присутствует в любом из элементов <option>, использование сочетания клавиш может привести к рассогласованию между исходным и пользовательским элементом. Однако большинство браузеров не поддерживают accesskey в элементах <option>.

Взаимодействие с клавиатурой

При открытом меню доступны следующие команды:

  • UP/LEFT: Перемещение фокуса на предыдущий элемент.
  • DOWN/RIGHT: Перемещение фокуса на следующий элемент.
  • END/PAGE DOWN: Перемещение фокуса на последний элемент.
  • HOME/PAGE UP: Перемещение фокуса на первый элемент.
  • ESCAPE: Закрытие меню.
  • ENTER/SPACE: Выбор выделенного элемента и закрытие меню.
  • ALT/OPTION + UP/DOWN: Переключение видимости меню.

При закрытом меню доступны следующие команды:

  • UP/LEFT: Выбор предыдущего элемента.
  • DOWN/RIGHT: Выбор следующего элемента.
  • END/PAGE DOWN: Выбор последнего элемента.
  • HOME/PAGE UP: Выбор первого элемента.
  • ALT/OPTION + UP/DOWN: Переключение видимости меню.
  • SPACE: Открытие меню.

Стилевые решения

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

  • ui-selectmenu-button: Элемент, подобный кнопке, заменяющий стандартный элемент selectmenu на странице. Имеет класс ui-selectmenu-button-closed при закрытии, и класс ui-selectmenu-button-open при открытии.
    • ui-selectmenu-text: Элемент span, представляющий текстовую часть элемента кнопки.
    • ui-selectmenu-icon: Иконка внутри кнопки selectmenu.
  • ui-selectmenu-menu: Обёрточный элемент вокруг меню, используемый для отображения вариантов пользователю (не само меню). При открытии меню добавляется класс ui-selectmenu-open.
    • ui-selectmenu-optgroup: Один из элементов, имитирующих элементы <optgroup> из стандартных select.

Зависимости

  • UI Core
  • Виджетный фабрикат
  • Position
  • Меню

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

  • Для работы данного виджета необходим функциональный CSS. Если вы создаёте собственную тему, используйте файл CSS виджета в качестве отправной точки.

Параметры

appendTo

Тип: Селектор
Значение по умолчанию: null
Элемент, в который будет добавлен список. Если значение равно null, проверяются родительские элементы <select> на наличие класса ui-front. Если такой элемент найден, список будет добавлен к нему. Независимо от значения, если элемент не найден, список будет добавлен к телу документа.
Примеры кода:

Инициализируйте selectmenu с указанием параметра appendTo.

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

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

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

classes

Тип: Объект
Значение по умолчанию:
{
  "ui-selectmenu-button-closed": "ui-corner-all",
  "ui-selectmenu-button-open": "ui-corner-top",
}

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

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

Инициализируйте selectmenu с указанием параметра classes, изменив стили для класса ui-selectmenu-menu.

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

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

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

disabled

Тип: Булево
Значение по умолчанию: false
Отключает selectmenu, если установлено значение true.
Примеры кода:

Инициализируйте selectmenu с указанием параметра disabled.

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

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

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

icons

Тип: Объект
Значение по умолчанию: { button: "ui-icon-triangle-1-s" }
Иконки для использования в кнопке, соответствующие иконке, определенной jQuery UI CSS Framework.
  • button (строка, по умолчанию: "ui-icon-triangle-1-s")
Примеры кода:

Инициализируйте selectmenu с указанием параметра icons.

$( ".selector" ).selectmenu({
  icons: { button: "ui-icon-circle-triangle-s" }
});

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

// Getter
var icons = $( ".selector" ).selectmenu( "option", "icons" );
 
// Setter
$( ".selector" ).selectmenu( "option", "icons", { button: "ui-icon-circle-triangle-s" } );

position

Тип: Объект
Значение по умолчанию: { my: "left top", at: "left bottom", collision: "none" }
Определяет положение меню относительно связанного элемента кнопки. Для получения дополнительной информации о различных параметрах обратитесь к утилите jQuery UI Position.
Примеры кода:

Инициализируйте selectmenu с указанием параметра position.

$( ".selector" ).selectmenu({
  position: { my : "left+10 center", at: "right center" }
});

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

// Getter
var position = $( ".selector" ).selectmenu( "option", "position" );
 
// Setter
$( ".selector" ).selectmenu( "option", "position", { my : "left+10 center", at: "right center" } );

width

Тип: Число или Булево
Значение по умолчанию: false
Ширина меню в пикселях. Если значение равно null, используется ширина исходного select. Если значение равно false, ширина не будет задаваться в стиле, что позволит задать ширину в таблице стилей.
Примеры кода:

Инициализируйте selectmenu с указанием параметра width.

$( ".selector" ).selectmenu({
  width: 200
});

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

// Getter
var width = $( ".selector" ).selectmenu( "option", "width" );
 
// Setter
$( ".selector" ).selectmenu( "option", "width", 200 );

Методы

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

Закрывает меню.
  • Этот метод не принимает аргументов.
Примеры кода:

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

$( ".selector" ).selectmenu( "close" );

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

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

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

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

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

Отключает selectmenu.
  • Этот метод не принимает аргументов.
Примеры кода:

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

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

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

Включает selectmenu.
  • Этот метод не принимает аргументов.
Примеры кода:

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

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

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

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

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

  • Этот метод не принимает аргументов.
Примеры кода:

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

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

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

Возвращает объект jQuery содержащий элемент меню.
  • Этот метод не принимает аргументов.
Примеры кода:

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

$( ".selector" ).selectmenu( "menuWidget" );

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

Открывает меню.
  • Этот метод не принимает аргументов.
Примеры кода:

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

$( ".selector" ).selectmenu( "open" );

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

Получает значение, в данный момент связанное с указанным optionName.

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

  • optionName
    Тип: Строка
    Название опции для получения.
Примеры кода:

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

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

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

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

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

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

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

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

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

  • optionName
    Тип: Строка
    Имя опции для установки.
  • value
    Тип: Объект
    Значение для установки опции.
Примеры кода:

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

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

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

Устанавливает одну или несколько опций для selectmenu.
  • options
    Тип: Объект
    Карта пар опция-значение для установки.
Примеры кода:

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

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

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

Парсит исходный элемент и повторно отрисовывает меню. Обрабатывает любые <option> или <optgroup> элементы, которые были добавлены, удалены или отключены.
  • Этот метод не принимает аргументов.
Примеры кода:

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

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

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

Возвращает объект jQuery содержащий элемент кнопки.
  • Этот метод не принимает аргументов.
Примеры кода:

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

$( ".selector" ).selectmenu( "widget" );

Точки расширения

Виджет selectmenu построен с помощью фабрики виджетов и может быть расширен. При расширении виджетов вы можете переопределять или добавлять поведение существующих методов. Следующие методы предоставляются в качестве точек расширения с той же стабильностью API, что и методы плагина, перечисленные выше. Более подробную информацию о расширениях виджетов см. в статье Расширение виджетов с помощью фабрики виджетов.

_renderButtonItem( item )Возвращает: jQuery

Метод, контролирующий создание сгенерированного содержимого кнопки. Метод должен создать и вернуть новый элемент.

  • item
    Тип: Объект
    • disabled
      Тип: Булево
      Указывает, отключен ли элемент.
    • element
      Тип: jQuery
      Ссылка на исходный <option> элемент элемента.
    • index
      Тип: Число
      Числовой индекс элемента.
    • label
      Тип: Строка
      Строка для отображения элемента.
    • optgroup
      Тип: Строка
      Если элемент находится внутри <optgroup>, это значение устанавливается в метку этого <optgroup>.
    • value
      Тип: Строка
      Атрибут value исходного <option> элемента.
Примеры кода:

Изменить цвет фона кнопки в зависимости от значения выбранного параметра.

_renderButtonItem: function( item ) {
  var buttonItem = $( "<span>", {
    "class": "ui-selectmenu-text"
  })
  this._setText( buttonItem, item.label );
 
  buttonItem.css( "background-color", item.value )
 
  return buttonItem;
}

_renderItem( ul, item )Возвращает: jQuery

Метод, контролирующий создание каждого параметра в меню виджета. Метод должен создать новый элемент <li>, добавить его в меню и вернуть его. Подробную информацию о разметке см. в документации к меню.

  • ul
    Тип: jQuery
    Элемент <ul>, в который должен быть добавлен созданный <li> элемент.
  • item
    Тип: Объект
    • element
      Тип: jQuery
      Исходный <option> элемент.
    • index
      Тип: Целое число
      Индекс <option> в <select>.
    • value
      Тип: Строка
      Значение <option>.
    • label
      Тип: Строка
      Метка <option>.
    • optgroup
      Тип: Строка
      Метка родительской optgroup, если есть.
    • disabled
      Тип: Булево
      Отключен ли <option>.
Примеры кода:

Изменить цвет фона элементов меню в зависимости от значения соответствующих элементов параметра.

_renderItem: function( ul, item ) {
  var li = $( "<li>" )
    .css( "background-color", item.value );
 
  if ( item.disabled ) {
    li.addClass( "ui-state-disabled" );
  }
 
  this._setText( li, item.label );
 
  return li.appendTo( ul );
}

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

Метод, контролирующий создание меню виджета. Методу передается пустой <ul> и массив элементов, основанных на <option> элементах в исходном <select>. Создание отдельных элементов <li> должно делегироваться методу _renderItemData(), который в свою очередь делегирует это в точку расширения _renderItem().
  • ul
    Тип: jQuery
    Пустой элемент <ul> для использования в качестве меню виджета.
  • items
    Тип: Массив
    Массив элементов, основанных на элементах <option> в исходном <select>. Подробности о формате объектов элементов см. в точке расширения _renderItem().
Примеры кода:

Добавить имя класса CSS к элементам меню с нечетными номерами.

Примечание: Для простоты в этом примере не поддерживаются группировки optgroup или отключенные элементы меню.
_renderMenu: function( ul, items ) {
  var that = this;
  $.each( items, function( index, item ) {
    that._renderItemData( ul, item );
  });
  $( ul ).find( "li" ).odd().addClass( "odd" );
}

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

Метод, отвечающий за изменение размера меню перед его отображением. Элемент меню доступен по адресу this.menu.
  • Этот метод не принимает никаких аргументов.
Примеры кода:

Всегда отображать меню шириной 500 пикселей.

_resizeMenu: function() {
  this.menu.outerWidth( 500 );
}

События

change( event, ui )Тип: selectmenuchange

Срабатывает, когда выбранный элемент был изменен. Не каждое событие select вызовет событие change.
  • event
    Тип: Событие
  • ui
    Тип: Объект
    • item
      Тип: jQuery
      Активный элемент.
Примеры кода:

Инициализировать selectmenu с указанным обратным вызовом change:

$( ".selector" ).selectmenu({
  change: function( event, ui ) {}
});

Привязать обработчик событий к событию selectmenuchange:

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

close( event )Тип: selectmenuclose

Срабатывает, когда меню скрыто.
  • event
    Тип: Событие

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

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

Инициализировать selectmenu с указанным обратным вызовом close:

$( ".selector" ).selectmenu({
  close: function( event, ui ) {}
});

Привязать обработчик событий к событию selectmenuclose:

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

create( event, ui )Тип: selectmenucreate

Срабатывает при создании selectmenu.
  • event
    Тип: Событие
  • ui
    Тип: Объект

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

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

Инициализировать selectmenu с указанным обратным вызовом create:

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

Привязать обработчик событий к событию selectmenucreate:

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

focus( event, ui )Тип: selectmenufocus

Срабатывает, когда элемент получает фокус.
  • event
    Тип: Событие
  • ui
    Тип: Объект
    • item
      Тип: jQuery
      Элемент, получивший фокус.
Примеры кода:

Инициализировать selectmenu с указанным обратным вызовом focus:

$( ".selector" ).selectmenu({
  focus: function( event, ui ) {}
});

Привязать обработчик событий к событию selectmenufocus:

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

open( event )Тип: selectmenuopen

Срабатывает при открытии меню.
  • event
    Тип: Событие

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

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

Инициализировать selectmenu с указанным обратным вызовом open:

$( ".selector" ).selectmenu({
  open: function( event, ui ) {}
});

Привязать обработчик событий к событию selectmenuopen:

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

select( event, ui )Тип: selectmenuselect

Срабатывает при выборе элемента меню.
  • event
    Тип: Событие
  • ui
    Тип: Объект
    • item
      Тип: jQuery
      Выбранный элемент.
Примеры кода:

Инициализировать selectmenu с указанным обратным вызовом select:

$( ".selector" ).selectmenu({
  select: function( event, ui ) {}
});

Привязать обработчик событий к событию selectmenuselect:

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

Примеры:

Простой jQuery UI Selectmenu

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>selectmenu demo</title>
  <link rel="stylesheet" href="//code.jquery.com/ui/1.12.1/themes/smoothness/jquery-ui.css">
  <style>
  label { display: block; }
  select { width: 200px; }
  </style>
  <script src="//code.jquery.com/jquery-1.12.4.js"></script>
  <script src="//code.jquery.com/ui/1.12.1/jquery-ui.js"></script>
</head>
<body>
 
<label for="speed">Select a speed:</label>
<select name="speed" id="speed">
  <option value="Slower">Slower</option>
  <option value="Slow">Slow</option>
  <option value="Medium" selected>Medium</option>
  <option value="Fast">Fast</option>
  <option value="Faster">Faster</option>
</select>
 
<script>
$( "#speed" ).selectmenu();
</script>
 
</body>
</html>

Демо:

Простой jQuery UI Selectmenu с optgroup

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>selectmenu demo</title>
  <link rel="stylesheet" href="//code.jquery.com/ui/1.12.1/themes/smoothness/jquery-ui.css">
  <style>
  label { display: block; }
  select { width: 200px; }
  </style>
  <script src="//code.jquery.com/jquery-1.12.4.js"></script>
  <script src="//code.jquery.com/ui/1.12.1/jquery-ui.js"></script>
</head>
<body>
 
<label for="files">Select a file:</label>
<select name="files" id="files">
  <optgroup label="Scripts">
    <option value="jquery">jQuery.js</option>
    <option value="jqueryui">ui.jQuery.js</option>
  </optgroup>
  <optgroup label="Other files">
    <option value="somefile">Some unknown file</option>
    <option value="someotherfile">Some other file</option>
  </optgroup>
</select>
 
<script>
$( "#files" ).selectmenu();
</script>
 
</body>
</html>

Демо:

jQuery UI Selectmenu с переполнением

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>selectmenu demo</title>
  <link rel="stylesheet" href="//code.jquery.com/ui/1.12.1/themes/smoothness/jquery-ui.css">
  <style>
  label { display: block; }
  select { width: 200px; }
  .overflow { height: 200px; }
  </style>
  <script src="//code.jquery.com/jquery-1.12.4.js"></script>
  <script src="//code.jquery.com/ui/1.12.1/jquery-ui.js"></script>
</head>
<body>
 
<label for="number">Select a number:</label>
<select name="number" id="number">
  <option value="1">1</option>
  <option value="2" selected>2</option>
  <option value="3">3</option>
  <option value="4">4</option>
  <option value="5">5</option>
  <option value="6">6</option>
  <option value="7">7</option>
  <option value="8">8</option>
  <option value="9">9</option>
  <option value="10">10</option>
  <option value="11">11</option>
  <option value="12">12</option>
  <option value="13">13</option>
  <option value="14">14</option>
  <option value="15">15</option>
  <option value="16">16</option>
  <option value="17">17</option>
  <option value="18">18</option>
  <option value="19">19</option>
</select>
 
<script>
$( "#number" )
  .selectmenu()
  .selectmenu( "menuWidget" )
    .addClass( "overflow" );
</script>
 
</body>
</html>

Демо:

© The jQuery Foundation and other contributors
Licensed under the MIT License.
https://api.jqueryui.com/selectmenu

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API