Spec-Zone.ru › jQuery UI

Виджет Spinner

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

Описание: Улучшает текстовое поле для ввода числовых значений с кнопками увеличения/уменьшения и обработкой клавиш со стрелками.

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

Параметры

классы
культура
отключено
иконки
инкрементальный
максимум
минимум
формат числа
страница
шаг

Методы

удалить
отключить
включить
экземпляр
действительно
параметр
страница вниз
страница вверх
шаг вниз
шаг вверх
значение
видет

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

_buttonHtml
_uiSpinnerHtml

События

изменение
создание
вращение
начало
остановка

Виджет Spinner, или числовой шаговый видет, идеально подходит для обработки числового ввода. Он позволяет пользователям вводить значение напрямую или изменять существующее значение, вращая с помощью клавиатуры, мыши или колесика мыши. В сочетании с Globalize, вы даже можете вращать валюты и даты в различных локалях.

Spinner оборачивает текстовое поле двумя кнопками для увеличения и уменьшения текущего значения. Добавляются события клавиш, чтобы можно было выполнять то же увеличение и уменьшение с помощью клавиатуры. Spinner делегирует Globalize для форматирования и анализа чисел.

В настоящее время Spinner поддерживает только Globalize 0.x. Поддержка Globalize 1.x в настоящее время не планируется.

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

  • UP: Увеличивает значение на один шаг.
  • DOWN: Уменьшает значение на один шаг.
  • PAGE UP: Увеличивает значение на одну страницу.
  • PAGE DOWN: Уменьшает значение на одну страницу.

Фокус остается в текстовом поле, даже после использования мыши для щелчка одной из кнопок вращения.

Когда спиннер не только для чтения (<input readonly>), пользователь может ввести текст, который приведет к недопустимому значению (ниже минимума, выше максимума, несовпадение шага, нечисловой ввод). Всякий раз, когда выполняется шаг, будь то программно или с помощью кнопок шагов, значение будет принудительно доведено до допустимого значения (см. описание для stepUp() и stepDown() для получения дополнительных сведений).

Тема

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

  • ui-spinner: Внешний контейнер спиннера.
    • ui-spinner-input: Элемент <input>, с которым был создан видет Spinner.
    • ui-spinner-button: Кнопки управления, используемые для увеличения и уменьшения значения спиннера. Кнопка вверх дополнительно будет иметь класс ui-spinner-up, а кнопка вниз — дополнительно класс ui-spinner-down.

Зависимости

  • UI Core
  • Производитель виджетов
  • Кнопка
  • Globalize (внешний, необязательный; для использования с параметрами culture и numberFormat)

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

  • Для работы этого виджета требуется функциональный CSS. Если вы создаете собственную тему, используйте файл CSS виджета в качестве отправной точки.
  • Этот видет программно изменяет значение своего элемента, поэтому событие change может не срабатывать при изменении значения элемента.
  • Создание спиннера на <input type="number"> не поддерживается из-за конфликта пользовательского интерфейса с родственным спиннером.

Параметры

classes

Type: Object
Default:
{
  "ui-spinner": "ui-corner-all",
  "ui-spinner-down": "ui-corner-br",
  "ui-spinner-up": "ui-corner-tr"
}

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

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

Инициализируйте вращатель с указанным параметром classes, изменив тему для класса ui-spinner:

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

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

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

culture

Type: String
Default: null
Устанавливает культуру, используемую для анализа и форматирования значения. Если null, используется текущая установленная культура в Globalize, см. документацию Globalize для доступных культур. Актуально только в том случае, если установлен параметр numberFormat. Требуется подключение Globalize.
Примеры кода:

Инициализируйте вращатель с указанным параметром culture:

$( ".selector" ).spinner({
  culture: "fr"
});

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

// Getter
var culture = $( ".selector" ).spinner( "option", "culture" );
 
// Setter
$( ".selector" ).spinner( "option", "culture", "fr" );

disabled

Type: Boolean
Default: false
Отключает вращатель, если установлен в true.
Примеры кода:

Инициализируйте вращатель с указанным параметром disabled:

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

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

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

icons

Type: Object
Default: { down: "ui-icon-triangle-1-s", up: "ui-icon-triangle-1-n" }
Иконки для использования в кнопках, соответствующие иконке, предоставляемой фреймворком CSS jQuery UI.
  • up (строка, по умолчанию: "ui-icon-triangle-1-n")
  • down (строка, по умолчанию: "ui-icon-triangle-1-s")
Примеры кода:

Инициализируйте вращатель с указанным параметром icons:

$( ".selector" ).spinner({
  icons: { down: "custom-down-icon", up: "custom-up-icon" }
});

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

// Getter
var icons = $( ".selector" ).spinner( "option", "icons" );
 
// Setter
$( ".selector" ).spinner( "option", "icons", { down: "custom-down-icon", up: "custom-up-icon" } );

incremental

Type: Boolean or Function( Integer count )
Default: true
Управляет количеством шагов, предпринимаемых при удержании кнопки вращения.
Поддерживается несколько типов:
  • Boolean: При установке в true, дельта шага будет увеличиваться при непрерывном вращении. При установке в false, все шаги равны (как определено параметром step).
  • Function: Получает один параметр: количество вращений, которые произошли. Должен вернуть количество шагов, которые должны произойти для текущего вращения.
Примеры кода:

Инициализируйте вращатель с указанным параметром incremental:

$( ".selector" ).spinner({
  incremental: false
});

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

// Getter
var incremental = $( ".selector" ).spinner( "option", "incremental" );
 
// Setter
$( ".selector" ).spinner( "option", "incremental", false );

max

Type: Number or String
Default: null
Максимально допустимое значение. Атрибут элемента max используется, если он существует, и параметр не установлен явно. Если null, максимальное значение не ограничивается.
Поддерживается несколько типов:
  • Number: Максимальное значение.
  • String: Если подключен Globalize, параметр max может быть передан как строка, которая будет анализироваться на основе параметров numberFormat и culture; в противном случае он вернется к собственному методу parseFloat().
Примеры кода:

Инициализируйте вращатель с указанным параметром max:

$( ".selector" ).spinner({
  max: 50
});

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

// Getter
var max = $( ".selector" ).spinner( "option", "max" );
 
// Setter
$( ".selector" ).spinner( "option", "max", 50 );

min

Type: Number or String
Default: null
Минимально допустимое значение. Атрибут элемента min используется, если он существует, и параметр не установлен явно. Если null, минимальное значение не ограничивается.
Поддерживается несколько типов:
  • Number: Минимальное значение.
  • String: Если подключен Globalize, параметр min может быть передан как строка, которая будет анализироваться на основе параметров numberFormat и culture; в противном случае он вернется к собственному методу parseFloat().
Примеры кода:

Инициализируйте вращатель с указанным параметром min:

$( ".selector" ).spinner({
  min: 0
});

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

// Getter
var min = $( ".selector" ).spinner( "option", "min" );
 
// Setter
$( ".selector" ).spinner( "option", "min", 0 );

numberFormat

Type: String
Default: null
Формат чисел, передаваемых в Globalize, если доступен. Наиболее распространенные - "n" для десятичного числа и "C" для значения валюты. См. также параметр culture.
Примеры кода:

Инициализируйте вращатель с указанным параметром numberFormat:

$( ".selector" ).spinner({
  numberFormat: "n"
});

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

// Getter
var numberFormat = $( ".selector" ).spinner( "option", "numberFormat" );
 
// Setter
$( ".selector" ).spinner( "option", "numberFormat", "n" );

page

Type: Number
Default: 10
Количество шагов, которые нужно сделать при прокрутке с помощью методов pageUp/pageDown.
Примеры кода:

Инициализируйте вращатель с указанным параметром page:

$( ".selector" ).spinner({
  page: 5
});

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

// Getter
var page = $( ".selector" ).spinner( "option", "page" );
 
// Setter
$( ".selector" ).spinner( "option", "page", 5 );

step

Type: Number or String
Default: 1
Размер шага, который нужно сделать при вращении с помощью кнопок или с помощью методов stepUp()/stepDown(). Атрибут элемента step используется, если он существует, и параметр не установлен явно.
Поддерживается несколько типов:
  • Number: Размер шага.
  • String: Если подключен Globalize, параметр step может быть передан как строка, которая будет анализироваться на основе параметров numberFormat и culture, в противном случае он вернется к собственному методу parseFloat.
Примеры кода:

Инициализируйте вращатель с указанным параметром step:

$( ".selector" ).spinner({
  step: 2
});

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

// Getter
var step = $( ".selector" ).spinner( "option", "step" );
 
// Setter
$( ".selector" ).spinner( "option", "step", 2 );

Методы

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

isValid()Возвращает: Булево

Возвращает, является ли значение Спиннера допустимым, учитывая его min, max и step.
  • Этот метод не принимает никаких аргументов.
Примеры кода:

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

var isValid = $( ".selector" ).spinner( "isValid" );

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

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

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

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

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

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

option()Возвращает: PlainObject

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Уменьшает значение на указанное количество страниц, как определено опцией page. Без параметра уменьшается на одну страницу.

Если полученное значение выше max, ниже min или приводит к несоответствию шага, значение будет скорректировано до ближайшего допустимого значения.

Вызов pageDown() приведет к срабатыванию событий start, spin и stop.

  • pages
    Тип: Число
    Количество страниц для уменьшения, по умолчанию 1.
Примеры кода:

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

$( ".selector" ).spinner( "pageDown" );

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

Увеличивает значение на указанное количество страниц, как определено опцией page. Без параметра увеличивается на одну страницу.

Если полученное значение выше max, ниже min или приводит к несоответствию шага, значение будет скорректировано до ближайшего допустимого значения.

Вызов pageUp() приведет к срабатыванию событий start, spin и stop.

  • pages
    Тип: Число
    Количество страниц для увеличения, по умолчанию 1.
Примеры кода:

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

$( ".selector" ).spinner( "pageUp", 10 );

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

Уменьшает значение на указанное количество шагов. Без параметра уменьшается на один шаг.

Если полученное значение выше max, ниже min или приводит к несоответствию шага, значение будет скорректировано до ближайшего допустимого значения.

Вызов stepDown() приведет к срабатыванию событий start, spin и stop.

  • steps
    Тип: Число
    Количество шагов для уменьшения, по умолчанию 1.
Примеры кода:

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

$( ".selector" ).spinner( "stepDown" );

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

Увеличивает значение на указанное количество шагов. Без параметра увеличивается на один шаг.

Если полученное значение выше max, ниже min или приводит к несоответствию шага, значение будет скорректировано до ближайшего допустимого значения.

Вызов stepUp() приведет к срабатыванию событий start, spin и stop.

  • steps
    Тип: Число
    Количество шагов для увеличения, по умолчанию 1.
Примеры кода:

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

$( ".selector" ).spinner( "stepUp", 5 );

value()Возвращает: Число

Получает текущее значение как число. Значение анализируется на основе опций numberFormat и culture.
  • Эта сигнатура не принимает никаких аргументов.
Примеры кода:

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

var value = $( ".selector" ).spinner( "value" );

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

  • value
    Тип: Число или Строка
    Значение для установки. Если передано в виде строки, значение анализируется на основе опций numberFormat и culture.
Примеры кода:

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

$( ".selector" ).spinner( "value", 50 );

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

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

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

var widget = $( ".selector" ).spinner( "widget" );

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

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

_buttonHtml()Возвращает: Строку

Метод, возвращающий HTML для кнопок увеличения и уменьшения спиннера. Каждой кнопке должен быть задан класс ui-spinner-button, чтобы работали связанные события.
  • Этот метод не принимает аргументы.
Примеры кода:

Используйте элементы <button> для кнопок увеличения и уменьшения.

_buttonHtml: function() {
  return "" +
    "<button class='ui-spinner-button ui-spinner-up'>" +
      "<span class='ui-icon " + this.options.icons.up + "'>&#9650;</span>" +
    "</button>" +
    "<button class='ui-spinner-button ui-spinner-down'>" +
      "<span class='ui-icon " + this.options.icons.down + "'>&#9660;</span>" +
    "</button>";
}

_uiSpinnerHtml()Возвращает: Строку

Метод, определяющий HTML для обёртки элемента <input> спиннера.
  • Этот метод не принимает аргументы.
Примеры кода:

Оберните спиннер элементом <div> без закруглённых углов.

_uiSpinnerHtml: function() {
  return "<div class='ui-spinner ui-widget ui-widget-content'></div>";
}

События

change( event, ui )Тип: spinchange

Срабатывает, когда значение спиннера изменилось, и вход больше не сфокусирован.
  • event
    Тип: Событие
  • ui
    Тип: Объект

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

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

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

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

Привяжите обработчик событий к событию spinchange:

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

create( event, ui )Тип: spincreate

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

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

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

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

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

Привяжите обработчик событий к событию spincreate:

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

spin( event, ui )Тип: spin

Срабатывает во время увеличения/уменьшения (для определения направления вращения сравните текущее значение с ui.value).

Может быть отменён, предотвращая обновление значения.

  • event
    Тип: Событие
  • ui
    Тип: Объект
    • value
      Тип: Число
      Новое значение, которое будет установлено, если событие не отменено.
Примеры кода:

Инициализируйте спиннер с указанным обратным вызовом для вращения:

$( ".selector" ).spinner({
  spin: function( event, ui ) {}
});

Привяжите обработчик событий к событию spin:

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

start( event, ui )Тип: spinstart

Срабатывает перед вращением. Может быть отменён, предотвращая вращение.
  • event
    Тип: Событие
  • ui
    Тип: Объект

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

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

Инициализируйте спиннер с указанным обратным вызовом для начала:

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

Привяжите обработчик событий к событию spinstart:

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

stop( event, ui )Тип: spinstop

Срабатывает после вращения.
  • event
    Тип: Событие
  • ui
    Тип: Объект

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

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

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

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

Привяжите обработчик событий к событию spinstop:

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

Пример:

Простой спиннер чисел

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>spinner demo</title>
  <link rel="stylesheet" href="https://code.jquery.com/ui/1.13.3/themes/smoothness/jquery-ui.css">
  <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>
 
<input id="spinner">
 
<script>
$( "#spinner" ).spinner();
</script>
 
</body>
</html>

Демо:

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

Spec-Zone.ru

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