Spinner Widget

Categories: Widgets

version added: 1.9

Description: 通过向上/向下按钮和箭头按键操作，增强文本输入框的数值输入功能。

QuickNavExamples

spinner（微调组件），或数步进控件（number stepper widget），是用于处理各种数字输入的完美控件。它允许用户直接输入一个值，或通过键盘、鼠标、滚轮微调改变一个已有的值。当与全球化（Globalize）结合时，您甚至可以微调显示不同地区的货币和日期。

spinner（微调组件）使用两个按钮将文本输入覆盖为当前值的递增值和递减值。spinner（微调组件）增加了按键事件，以便可以用键盘完成相同的递增和递减。spinner（微调组件）代表全球化（Globalize）的数字格式和解析。

键盘交互（Keyboard interaction）

UP：对值增加一步。
DOWN：对值减少一步。
PAGE UP：对值增加一页。
PAGE DOWN：对值减少一页。

用鼠标点击微调按钮后，焦点仍停留在文本域中。

当spinner（微调组件）不是只读（<input readonly>）时，用户可以输入值，这可能会产生无效的值（小于最小值，大于最大值，增减错配，非数字输入）。当增减时，不管通过编程方式还是微调按钮方式，值都会被强制为一个有效值（如需了解详情，请查看 stepUp() 和 stepDown() 的描述。

主题（Theming）

spinner（微调组件）使用 jQuery UI CSS 框架来定义它的外观和感观的样式。如果需要使用spinner（微调组件）指定的样式，则可以使用下面的 CSS class 名称：

ui-spinner：spinner（微调组件）的外层容器。
- ui-spinner-input：spinner（微调组件）实例化的 <input> 元素。
- ui-spinner-button：用于递增或递减spinner（微调组件）值的按钮控件。向上按钮会另外带有一个 ui-spinner-up class，向下按钮会另外带有一个 ui-spinner-down class。

依赖（Dependencies）

UI 核心（UI Core）
部件库（Widget Factory）
按钮部件（Button Widget）
全球化（Globalize）（外部的，可选的；当与 culture 和 numberFormat 选项一起使用时）

Additional Notes:

该部件要求一些功能性的 CSS，否则将无法工作。如果您创建了一个自定义的主题，请使用小部件指定的 CSS 文件作为起点。
该部件以编程方式操作元素的值，因此当元素的值改变时不会触发原生的 change 事件。
不支持在 <input type="number"> 上创建选择器，因为会造成与本地spinner（微调组件）的 UI 冲突。

Options

cultureType: String

Default: null设置culture选项用于解析和格式化值。如果为null，在Globalize下当前设置的culture将被使用，可供的culture，请查看Globalize 文档。只有当numberFormat选项设置了，才会有关联。需要引用Globalize。Code examples:

初始化带有指定 culture选项的 spinner：

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

在初始化后，获取或设置culture 选项：

// getter
var culture = $( ".selector" ).spinner( "option", "culture" );

// setter
$( ".selector" ).spinner( "option", "culture", "fr" );

disabledType: Boolean

Default: false如果设置为 true，则禁用该 spinner（微调组件）。Code examples:

初始化带有指定 disabled选项的 spinner：

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

在初始化后，获取或设置disabled 选项：

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

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

iconsType: Object

Default: { down: "ui-icon-triangle-1-s", up: "ui-icon-triangle-1-n" }标题要使用的图标，与 jQuery UI CSS 框架提供的图标（Icons）匹配。设置为 false 则不显示图标。

up (string, default: "ui-icon-triangle-1-n")
down (string, default: "ui-icon-triangle-1-s")

Code examples:

初始化带有指定 icons选项的 spinner：

$( ".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" } );

incrementalType: Boolean or Function( Integer count )

Default: true当按住spinner（微调组件）按钮不放时，控制的步数。支持多个类型：

Boolean:如果设置为true，当按住spinner（微调组件）按钮不放时，数值会根据step选项的值不断的增加或减少。当设置为false时，所有步骤都是相等的，（由step选项所定义）（愚人码头注：点一下，数值会根据step选项的值增加或减少一步）。
Function: 接收一个参数：已发生的自旋数。必须返回在当前发生的微调的步数。

Code examples:

初始化带有指定 incremental选项的 spinner：

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

在初始化后，获取或设置incremental 选项：

// getter
var incremental = $( ".selector" ).spinner( "option", "incremental" );

// setter
$( ".selector" ).spinner( "option", "incremental", false );

maxType: Number or String

Default: null允许的最大值。如果元素的max属性存在，该选项未明确设置，那么该元素的max属性就被用作该选项的值。如果为null，表示没有上限。支持多个类型：

Number: 最大值。
String: 如果应用包含了Globalize， max选项可以传递可以被 numberFormat和culture选项解析的字符串。否则求助原生的parseFloat()将方法。

Code examples:

初始化带有指定 max选项的 spinner：

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

在初始化后，获取或设置max 选项：

// getter
var max = $( ".selector" ).spinner( "option", "max" );

// setter
$( ".selector" ).spinner( "option", "max", 50 );

minType: Number or String

Default: null允许的最小值。如果元素的min属性存在，该选项未明确设置，那么该元素的min属性就被用作该选项的值。如果为null，表示没有下限。支持多个类型：

Number: 最小值。
String: 如果应用包含了Globalize， max选项可以传递可以被 numberFormat和culture选项解析的字符串。否则使用原生的parseFloat()方法解析。

Code examples:

初始化带有指定 min选项的 spinner：

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

在初始化后，获取或设置min 选项：

// getter
var min = $( ".selector" ).spinner( "option", "min" );

// setter
$( ".selector" ).spinner( "option", "min", 0 );

numberFormatType: String

Default: null通过Globalize格式化数字，如果有效的话。最常见的用于"n"用作十进制数和"C"用作货币值。也看到了culture选择。Code examples:

初始化带有指定 numberFormat选项的 spinner：

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

在初始化后，获取或设置numberFormat 选项：

// getter
var numberFormat = $( ".selector" ).spinner( "option", "numberFormat" );

// setter
$( ".selector" ).spinner( "option", "numberFormat", "n" );

pageType: Number

Default: 10当通过pageUp/pageDown的方法进行分页时，采取的步数。Code examples:

初始化带有指定 page选项的 spinner：

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

在初始化后，获取或设置page 选项：

// getter
var page = $( ".selector" ).spinner( "option", "page" );

// setter
$( ".selector" ).spinner( "option", "page", 5 );

stepType: Number or String

Default: 1通过按钮或stepUp()/stepDown()方法微调时，采取的步数。如果元素的step属性存在，并且该选项未明确设置，那么元素的step属性值将作为该选项的值使用。支持多个类型：

Number: 步数
String: 如果应用包含了Globalize， max选项可以传递可以被 numberFormat和culture选项解析的字符串。否则使用原生的parseFloat()方法解析。

Code examples:

初始化带有指定 step选项的 spinner：

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

在初始化后，获取或设置step 选项：

// getter
var step = $( ".selector" ).spinner( "option", "step" );

// setter
$( ".selector" ).spinner( "option", "step", 2 );

Methods

destroy()Returns: jQuery (plugin only)

完全移除 spinner功能。这会把元素返回到它的预初始化状态。

该方法不接受任何参数。

Code examples:

调用 destroy 方法：

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

disable()Returns: jQuery (plugin only)

禁用 spinner.

该方法不接受任何参数。

Code examples:

调用 disable 方法：

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

enable()Returns: jQuery (plugin only)

启用 spinner.

该方法不接受任何参数。

Code examples:

调用 enable 方法：

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

option( optionName )Returns: Object

获取当前与指定的 optionName 关联的值。

optionNameType: String要获取值的选项的名称。

Code examples:

调用该方法：

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

option()Returns: PlainObject

获取一个包含键/值对的对象，键/值对表示当前 spinner 选项哈希。

该方法不接受任何参数。

Code examples:

调用该方法：

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

option( optionName, value )Returns: jQuery (plugin only)

设置与指定的 optionName 关联的 spinner 选项的值。

optionNameType: String要设置的选项的名称。
valueType: Object要为选项设置的值。

Code examples:

调用该方法：

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

option( options )Returns: jQuery (plugin only)

为 spinner 设置一个或多个选项。

optionsType: Object要设置的 option-value 对。

Code examples:

调用该方法：

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

pageDown( [pages ] )Returns: jQuery (plugin only)

通过指定页数递减值，页数由page选项定义。如果没有参数，单页递减。

如果返回值大于max选项定义的值，小于min选项定义的值，或返回的结果步数不匹配，那么该值将被调整到最接近的有效值。

调用pageDown()将引起start, spin, 和 stop 事件被触发。

pagesType: Number递减的页数，默认是1.

Code examples:

调用 pageDown 方法：

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

pageUp( [pages ] )Returns: jQuery (plugin only)

通过指定页数递增值，页数由page选项定义。如果没有参数，单页递增。

如果返回值大于max选项定义的值，小于min选项定义的值，或返回的结果步数不匹配，那么该值将被调整到最接近的有效值。

调用pageUp()将引起start, spin, 和 stop 事件被触发。

pagesType: Number递增的页数，默认是1.

Code examples:

调用 pageUp 方法：

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

stepDown( [steps ] )Returns: jQuery (plugin only)

通过指定步数递减值，步数由step选项定义。如果没有参数，单步递减。

如果返回值大于max选项定义的值，小于min选项定义的值，或返回的结果步数不匹配，那么该值将被调整到最接近的有效值。

调用stepDown()将引起start, spin, 和 stop 事件被触发。

stepsType: Number递减的步数，默认是1.

Code examples:

调用 stepDown 方法：

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

stepUp( [steps ] )Returns: jQuery (plugin only)

通过指定步数递增值，步数由step选项定义。如果没有参数，单步递增。

如果返回值大于max选项定义的值，小于min选项定义的值，或返回的结果步数不匹配，那么该值将被调整到最接近的有效值。

调用pageUp()将引起start, spin, 和 stop 事件被触发。

stepsType: Number递增的步数，默认是1.

Code examples:

调用 stepUp 方法：

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

value()Returns: Number

获取当前数值，这个值是基于numberFormat 和 culture选项解析的。

该方法不接受任何参数。

Code examples:

调用该方法：

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

value( value )Returns: jQuery (plugin only)

设置当前值

valueType: Number or String用来设置的值。如果传递的是一个字符串，那么这个值是基于numberFormat 和 culture选项解析的。

Code examples:

调用该方法：

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

widget()Returns: jQuery

返回包含生成组件包裹元素的一个jQuery对象。

该方法不接受任何参数。

Code examples:

调用 widget 方法：

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

扩展点（Extension Points）

spinner（微调组件）是widget factory构建的，并且可以扩展。当扩展部件时，你必须覆盖或添加新的行为到现有的方法。下列方法被提供作为扩展点用相同的API稳定性如上所列的plugin methods。有关小部件扩展的更多信息，请参阅使用Widget Factory 扩展小部件。

_buttonHtml()Returns: String

这个方法返回的HTML用于spinner（微调组件）的递增和递减按钮。每个按钮都必须给定一个ui-spinner-button的类名用于相关联的事件工作。

该方法不接受任何参数。

Code examples:

使用<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()Returns: String

这个方法返回的HTML用于包裹 spinner（微调组件）<input>元素。

该方法不接受任何参数。

Code examples:

用没有圆角的<div> 包裹 spinner（微调组件）。

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

Events

change( event, ui )Type: `spinchange`

当spinner微调器的值改变并且输入元素（input）失去焦点时，该事件触发。

eventType: Event
uiType: Object

注意：ui 对象是空的，这里包含它是为了与其他事件保持一致性。

Code examples:

初始化带有指定 change 回调的 spinner（微调器）：

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

绑定一个事件监听器到 spinchange 事件：

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

create( event, ui )Type: `spincreate`

当spinner微调器创建的时候，该时间触发。

eventType: Event
uiType: Object

注意：ui 对象是空的，这里包含它是为了与其他事件保持一致性。

Code examples:

初始化带有指定 create 回调的 spinner（微调器）：

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

绑定一个事件监听器到 spincreate 事件：

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

spin( event, ui )Type: `spin`

在递增/递减的时候，该事件触发（用当前值和ui.value比较来确定的微调的方向）。

可以取消，以防止被更新值。

eventType: Event
uiType: Object
- valueType: Number要设置的新值，除非该事件被取消。/div>

Code examples:

初始化带有指定 spin 回调的 spinner（微调器）：

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

绑定一个事件监听器到 spin 事件：

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

start( event, ui )Type: `spinstart`

微调开始之前，触发该事件。可以取消，以防止微调。

eventType: Event
uiType: Object

注意：ui 对象是空的，这里包含它是为了与其他事件保持一致性。

Code examples:

初始化带有指定 start 回调的 spinner（微调器）：

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

绑定一个事件监听器到 spinstart 事件：

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

stop( event, ui )Type: `spinstop`

微调结束后，触发该事件。

eventType: Event
uiType: Object

注意：ui 对象是空的，这里包含它是为了与其他事件保持一致性。

Code examples:

初始化带有指定 stop 回调的 spinner（微调器）：

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

绑定一个事件监听器到 spinstop 事件：

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

Example:

普通的数字微调器。

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>spinner demo</title>
  <link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
  <script src="//code.jquery.com/jquery-1.10.2.js"></script>
  <script src="//code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>

<input id="spinner">

<script>
$( "#spinner" ).spinner();
</script>

</body>
</html>

version added: 1.9

QuickNavExamples

Options

Methods

Extension Points

Events

键盘交互（Keyboard interaction）

主题（Theming）

依赖（Dependencies）

Additional Notes:

Options

cultureType: String

disabledType: Boolean

iconsType: Object

incrementalType: Boolean or Function( Integer count )

maxType: Number or String

minType: Number or String

numberFormatType: String

pageType: Number

stepType: Number or String

Methods

destroy()Returns: jQuery (plugin only)

disable()Returns: jQuery (plugin only)

enable()Returns: jQuery (plugin only)

option( optionName )Returns: Object

option()Returns: PlainObject

option( optionName, value )Returns: jQuery (plugin only)

option( options )Returns: jQuery (plugin only)

pageDown( [pages ] )Returns: jQuery (plugin only)

pageUp( [pages ] )Returns: jQuery (plugin only)

stepDown( [steps ] )Returns: jQuery (plugin only)

stepUp( [steps ] )Returns: jQuery (plugin only)

value()Returns: Number

value( value )Returns: jQuery (plugin only)

widget()Returns: jQuery

扩展点（Extension Points）

_buttonHtml()Returns: String

_uiSpinnerHtml()Returns: String

Events

change( event, ui )Type: spinchange

create( event, ui )Type: spincreate

spin( event, ui )Type: spin

start( event, ui )Type: spinstart

stop( event, ui )Type: spinstop

Example:

普通的数字微调器。

change( event, ui )Type: `spinchange`

create( event, ui )Type: `spincreate`

spin( event, ui )Type: `spin`

start( event, ui )Type: `spinstart`

stop( event, ui )Type: `spinstop`