目录

Spinner Widget

优质
小牛编辑
125浏览
2023-12-01

Categories: Widgets

version added: 1.9

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

QuickNavExamples

Options

Methods

Extension Points

Events

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)

Additional Notes:

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

Options

cultureType: String

Default: null设置culture选项 用于解析和格式化值。 如果为null,在Globalize下当前设置的culture将被使用, 可供的culture,请查看Globalize 文档。 只有当numberFormat选项设置了,才会有关联。 需要引用GlobalizeCode 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: 如果应用包含了Globalizemax选项可以传递可以被 numberFormatculture选项解析的 字符串。 否则求助原生的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: 如果应用包含了Globalizemax选项可以传递可以被 numberFormatculture选项解析的 字符串。 否则使用原生的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: 如果应用包含了Globalizemax选项可以传递可以被 numberFormatculture选项解析的 字符串。 否则使用原生的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

获取当前数值,这个值是基于numberFormatculture选项解析的。

  • 该方法不接受任何参数。

Code examples:

调用该方法:

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

value( value )Returns: jQuery (plugin only)

设置当前值

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 + "'>▲</span>" +
    "</button>" +
    "<button class='ui-spinner-button ui-spinner-down'>" +
      "<span class='ui-icon " + this.options.icons.down + "'>▼</span>" +
    "</button>";
}

_uiSpinnerHtml()Returns: String

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

  • 该方法不接受任何参数。

Code examples:

用没有圆角的&lt;div&gt; 包裹 spinner(微调组件)。

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

Events

change( event, ui )Type: spinchange

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

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

Code examples:

初始化带有指定 change 回调的 spinner(微调器):

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

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

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

create( event, ui )Type: spincreate

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

注意: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

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

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

Code examples:

初始化带有指定 start 回调的 spinner(微调器):

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

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

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

stop( event, ui )Type: spinstop

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

注意: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>