jQuery UI 學習筆記 (五) : 微調器 (Spinner)

Spinner (微調器) 是處理數字的好用小工具, 它有兩個小按鈕分別用來將數字框中的數字調上或調下, 典型的應用例如調色盤中 RGB 的數值調整, 或是在 Google Map 中用來將比例調大或縮小 :

jQuery UI 的 Spinner 事實上是 input 輸入框變身而來的, 其 HTML 部分必須要指定一個 id 屬性 :

<input id="spinner1"> 

在 jQuery 程式部分只要呼叫 spinser() 函數即可 :

$("spinner1").spinner();

例如 :

測試 1 : Spinner 測試 : 預設微調器 [看原始碼]

結果如下 :

按右方的上下鈕, 起始值為 1, 每次跳躍值為 1. 也可以按 Page Up 或 Page Down 鈕, 但每次跳躍值為 10.

上面所建立的 Spinner 並未傳入設定選項, 因此都用預設值來設定. 事實上 Spinner 有如下常用選項可變更其預設值 :

常用 options	說明
min	最小值 (預設 null)
max	最大值 (預設 null)
step	按上下鈕跳躍之數值 (預設 1)
page	按 Pg Up 與 Pg Dn 鈕時要跳躍的 step 數 (預設 10)
disabled	禁能 (True/False), 預設 False

除了按 Spinner 上的上下按鈕調整數值外, 還可以按鍵盤上的 Page Up 與 Page Down 來調整, 注意, 其一次跳躍值是 page 乘以 step, 因為 page 屬性是指一次跳幾個 step 之意 (預設 10), 例如 :


測試 2 : Spinner 測試 : 傳入選項物件 [看原始碼]

HTML 部分 : 同測試 1

jQuery 部分 :

      var config={
        min: 0,
        max: 255,
        page: 5,
        step: 2
        }
      $("#spinner1").spinner(config);

此例 step=2, 按 Spinner 上面的上下鈕每次跳躍值為 2; 但若按 Page Up 與 Page Down 鍵, 則每次跳躍值為 page*step=5*2=10, 因 page 被改為 5 了, 若未設 page: 5, 則預設一次跳 10, 每按一次 PgUp 或 Pg Dn 會跳 10*2=20.

Spinner 的方法如下表 :

常用 method	說明
value	取得目前值或設定新值
option	取得或設定屬性之值
disable	禁能 (等於 disabled 屬性=True)
enable	致能 (等於 disabled 屬性=False)
pageUp	設定按下 PageUp 時跳幾個 page
pageDown	設定按下 PageDown 時跳幾個 page
stepUp	設定向上增加指定之 step 值
stepDown	設定向下減少指定之 step 值

jQuery UI 元件 (widget) 的方法呼叫方式是將方法名稱以字串格式做為第一參數傳入, 只有一個參數時為 getter (有傳回值), 有兩個參數時為 setter (第二個參數為設定值) :

var ret=$("#id").widgetName("method");     //getter
$("#id").widgetName("method", value);     //setter

但 option 方法有 2~3 個參數, 其第二參數為選項名稱, 第三參數為設定值 :

var opt=$("#id").widgetName("option", "optionName");     //getter
$("#id").widgetName("option", "optionName", value);     //setter

例如 :

測試 3 : Spinner 測試 : option 方法 [看原始碼]

HTML 部分 : 同測試 1

jQuery 部分 :

      var config={}
      $("#spinner1").spinner(config);
      $("#toggle").click(function(e) {
        var text=$("#toggle").html();
        if (text=="Disable") {  //可用狀態
          $("#spinner1").spinner("option", "disabled", true);
          $("#toggle").html("Enable");
          }
        else {  //不可用狀態
          $("#spinner1").spinner("option", "disabled", false);
          $("#toggle").html("Disable");
          }
        });

此例有一個按鈕, 初始顯示 Disable, 按一下會將 Spinner 禁能, 同時按鈕顯示也變成 Enable, 再按一下使 Spinner 致能, 按鈕恢復顯示 Disable, 如此反覆循環 (Toggle).

上面的範例也可以直接呼叫 disable 與 enable 方法來做, 例如 :

測試 4 : Spinner 測試 : disable 與 enable 方法 [看原始碼]

      var config={}
      $("#spinner1").spinner(config);
      $("#toggle").click(function(e) {
        var text=$("#toggle").html();
        if (text=="Disable") {
          $("#spinner1").spinner("disable"); 
          $("#toggle").html("Enable");
          }
        else {
          $("#spinner1").spinner("enable");
          $("#toggle").html("Disable");
          }
        });

此例效果與上面範例三相同. 下面則是 stpUp 與 stepDown 方法之範例 :

測試 5 : Spinner 測試 : stepUp 與 stepDown 方法 [看原始碼]

      var config={
        min: 0,
        max: 100
        }
      $("#spinner1").spinner(config);
      $("#stepUp").click(function(e) {
        $("#spinner1").spinner("stepUp", 5);
        });
      $("#stepDown").click(function(e) {
        $("#spinner1").spinner("stepDown", 5);
        });

此例有兩個按鈕 stepUp 5 與 stepDown 5 顧名思義一個按下去數值會往上跳 5, 另一個則是往下跳 5.

方法 pageUp 與 pageDown 用來設定一次要跳幾個 page (預設一個 page 為 10), 若 pageUp 設為 2, 表示按 Pg Up 鈕會跳 2*10 個單位 (1 個單位即 step 選項所定), 例如 :

測試 6 : Spinner 測試 : pageUp 與 pageDown 方法 [看原始碼]

      var config={
        min: 0,
        max: 100,
        step: 2
        }
      $("#spinner1").spinner(config);
      $("#pageUp").click(function(e) {
        $("#spinner1").spinner("pageUp", 2);
        });
      $("#pageDown").click(function(e) {
        $("#spinner1").spinner("pageDown", 2);
        });

此例 step 設為 2, 當按下按鍵時呼叫 pageUp 與 pageDown 並傳入 2, 表示要跳躍 2 個 page, 預設 1 個 page 為 10 個單位, 故每按一次跳 2*10=20 單位, 而每個單位為 step=2, 故每按一次跳 40.

下面為更改 page=5 範例 :

測試 7 : Spinner 測試 : pageUp 與 pageDown 方法 [看原始碼]

HTML 部分 :

  <input id="spinner1">
  <button id="pageUp" class="ui-button ui-widget ui-corner-all">pageUp 2</button>
  <button id="pageDown" class="ui-button ui-widget ui-corner-all">pageDown 2</button>

jQuery 部分 :

      var config={
        min: 0,
        max: 100,
        page: 5
        }
      $("#spinner1").spinner(config);
      $("#pageUp").click(function(e) {
        $("#spinner1").spinner("pageUp", 2);
        });
      $("#pageDown").click(function(e) {
        $("#spinner1").spinner("pageDown", 2);
        });

此例 step 為預設值 1, 僅更改 page 由預設值 10 改成 5, 即每頁 5 個單位. 當按下按鍵時呼叫 pageUp 與 pageDown 並傳入 2, 表示要跳躍 2 個 page, 1 個 page 現在為 5 個單位, 故每按一次跳 2*5=10 單位, 而每個單位為 step=1, 故每按一次跳 10.

還有一個方法 value 用來設定或取得 Spinner 之值, 設定較少用, 取得較常用, 通常會與事件一起使用. Spinner 常用的方法如下表 :

常用 event	說明
change	值已改變且輸入框失焦時觸發
stop	停止按 Spiiner 按鈕且輸入框失焦時觸發
start	開始按 Spiiner 按鈕時觸發
spin	Spiiner 按鈕被按下時觸發

指定事件處理有兩種方式, 一是使用 jQuery UI 的方式 :

var handler=function(e, ui) {};
$("#widget_id").spinner({事件: handler});  //事件例如 spin

第二種方式使用 jQuery 的 on() :

var handler=function(e, ui) {};
$("#widget_id").on("事件", handler);

下面以調色盤為例說明 value 方法與 spin 事件之用法 :

測試 8 : Spinner 測試 : value 方法與 spin 事件處理 [看原始碼]

HTML 部分 :

  <p>R <input id="red"></p>
  <p>G <input id="green"></p>
  <p>B <input id="blue"></p>
  <div id="canvas" style="width:200px;height:100px;border-style:solid;">

jQuery 部分 :

      var setcolor=function() {
        var r=$("#red").spinner("value");
        var g=$("#green").spinner("value");
        var b=$("#blue").spinner("value");
        var bgcolor="rgb(" + r + "," + g + "," + b + ")";
        $("#canvas").css("background-color", bgcolor);
        };
      $("#red").spinner({min: 0, max: 255, spin: setcolor});
      $("#green").spinner({min: 0, max: 255, spin: setcolor});
      $("#blue").spinner({min: 0, max: 255, spin: setcolor});

此例 HTML 有三個 spinner 以及一個 div 畫布, 先定義一個 setColor 函數給 Spinner 的 spin 事件呼叫, 然後在呼叫 spinner() 時傳入含有 spin 事件屬性的設定物件即可.

上面範例是透過設定物件的 spin 物件指定一個 spin 事件的處理函數, 事實上也可以利用 jQuery 本身的 on() 方法綁定 spin 事件來達成同樣效果; 同樣地, Spinner 的取值除了用其 value 方法外, 也可以直接使用 jQuery 的 val() 方法, 例如 :

測試 9 : Spinner 測試 : value 方法與 spin 事件處理 [看原始碼]

HTML 部分 : 同測試 8

jQuery 部分 :

      var setColor=function(e, ui) {
        var r=$("#red").val();
        var g=$("#green").val();
        var b=$("#blue").val();
        var bgcolor="rgb(" + r + "," + g + "," + b + ")";
        $("#canvas").css("background-color", bgcolor);
        };
      var config={min: 0, max: 255};
      $("#red").spinner(config);
      $("#green").spinner(config);
      $("#blue").spinner(config);   
      $("#red").on("spin", setColor);
      $("#green").on("spin", setColor);
      $("#blue").on("spin", setColor);

注意, 若監聽的是 stop 事件, 使用 on() 時傳入之第一參數為 "spinstop", 其餘事件對應如下表所示 :

Spinner event	jQuery on() 第一參數
spin	"spin"
change	"spinchange"
stop	"spinstop"
start	"spinstart"

例如將上面測試 9 改成 stop 事件觸發如下 :

測試 10 : Spinner 測試 : value 方法與 stop 事件處理 [看原始碼]

HTML 部分 : 同上

jQuery 部分 :

      var setColor=function(e, ui) {
        var r=$("#red").val();
        var g=$("#green").val();
        var b=$("#blue").val();
        var bgcolor="rgb(" + r + "," + g + "," + b + ")";
        $("#canvas").css("background-color", bgcolor);
        };
      var config={min: 0, max: 255};
      $("#red").spinner(config);
      $("#green").spinner(config);
      $("#blue").spinner(config);   
      $("#red").on("spinstop", setColor);
      $("#green").on("spinstop", setColor);
      $("#blue").on("spinstop", setColor);

此例是停止增減時才觸發.