jQuery API 文件查詢使用

tags: OKR 共同教學 jQuery

2020/05/19(Update:2020/06/13)

參考資源網站

jQuery官網-jQuery API Documentation
easing函數速查表
w3school jQuery animate()

分享說明

針對jQuery官網上的API文件，將專案上可能較常使用的基本函式挑選出來學習，理解函式如何使用，若有寫的不清楚的地方歡迎提供補充。

一、Attributes(Dom屬性)

addClass() 增加樣式

addClass()與removeClass()CodePen範例

一、使用方式

.addClass(className) 
為某個元素增加指定的樣式名稱
Type: String (字串)
Type: Array (陣列)

.addClass(function(index, currentClass))
傳遞一個用來設置樣式類名的函數，返回一個或更多用空格隔開的要增加的樣式名
Type: function() (函數)

二、範例寫法

1. 為元素增加指定的樣式名稱可以是一個或多個，用空格隔開

$('p').addClass('className');
$('p').addClass('className1 className2');

2. 在jQuery3.3開始支援多個樣式使用Array(陣列)寫法，陣列請用[]，多樣式中間以逗號區隔

$('p').addClass(['className1','className2']);

3. 也可以搭配removeClass()相互切換元素樣式

$('p').removeClass('className1').addClass('className2');

4. addClass()方法的參數可以接收function()函數

//這範例是說可以為每個<li>增加class
//index代表回傳數字，從0開始

$('ul li').addClass(function(index) {
  return "item-"+index; //回傳item-0,item-1,item-2...
});

//這範例是說要在當前有class="red"裡，在增加一個class="green"

$('div').addClass(function(index,currentClass)){
    var classAdd; //宣告一個要增加的class

    if(currentClass==="red"){
        addClass="green";
        $('p').text("change text")；//然後p裡面的文字則會變更
    }
    return classAdd;
}

removeClass() 移除樣式

addClass()與removeClass()CodePen範例

一、使用方式

.removeClass(className) 
為某個元素增加指定的樣式名稱
Type: String(字串)
Type: Array(陣列)

.removeClass(function(index, currentClass))
傳遞一個用來設置樣式類名的函數，返回一個或更多用空格隔開的要增加的樣式名
Type: function()

二、範例寫法

1. 為元素增加指定的樣式名稱可以是一個或多個，用空格隔開

$('p').removeClass('className');
$('p').removeClass('className1 className2');

2. 也可以搭配removeClass()相互切換元素樣式

$('p').removeClass('className1').addClass('className2');

toggleClass() 切換樣式

toggleClass()CodePen範例

toggleClass()＝addClass()與removeClass
以下範例為當點選p標籤時，會切換class="hightlight"增加/移除

<p class="blue">Click to toggle</p>

$('p').click(function(){
  //當下點選的p區塊會增加class="hightlight"
  $(this).toggleClass('hightlight');
})

hasClass() 判斷有否樣式

hasClass()CodePen範例

<div id="mydiv" class="foo bar"></div>

//會去看id="mydiv"裡面是否有class="foo"
$('#mydiv').hasClass('foo')； 

//假如有class="foo"，console會回傳true，若沒有回傳false

var mydiv = $('#mydiv').hasClass('foo');
console.log(mydiv);

attr() 獲取元素屬性值

attr()／remoceAttr()／prop()CodePen範例

一、使用方式

.attr(attributeName) 
$('em').attr('title');

.attr(attributeName, value)
$('em').attr('title','hello,my friend');

二、範例寫法

1. 取得元素中的屬性值

<em title="hello,my friend">large</em> 
<div></div>

var title = $('em').attr('title');
$('div').text(title);

//印出結果
hello,my friend

2. 取得元素中並設定/更改屬性值

<em title="hello,my friend">large</em> 
<div></div>

$('em').attr('title','Goodybye,my friend');

3. 一次設置多個屬性值

//印出結果
<em title="Goodybye,my friend">large</em>

<img src="https://picsum.photos/200/300">

$('img').attr({
    width:"300",
    height:"180"
});

//印出結果
<img src="https://picsum.photos/200/300" width="300" height="180">

4. 使用function()一次修改多個元素屬性

//印出結果
<div class="demo4">
  <img title="img1.gif">
  <img title="img2.gif">
  <img title="img3.gif">
</div>

$('.demo4 img').attr('src',function(){
    return "/images/" + this.title;
    //新增src屬性，並給予圖片路徑的名稱抓取為title內容
})

//印出結果
<div class="demo4">
  <img title="img1.gif" src="/images/img1.gif">
  <img title="img2.gif" src="/images/img2.gif">
  <img title="img3.gif" src="/images/img3.gif">
</div>

5. 取得屬性狀態值

//取值的時候，假如input本身有設定html屬性checked，就要使用.attr()取得字串checked
<input class="check1" type="checkbox" checked>

//若沒有設定，則會取到undefined
<input class="check2" type="checkbox">

//使用.prop()取該屬性checked值，則會取得布林值(boolean)
<input class="check3" type="checkbox" checked="true"> 
<input class="check4" type="checkbox" checked="false"> 

$('.check-1').attr('checked') //checked
$('.check-2').attr('checked') //undefined
$('.check-3').prop('checked') //true
$('.check-4').prop('checked') //false

removeAttr() 刪除元素屬性值

可與attr()搭配應用

attr()／remoceAttr()／prop()CodePen範例

.removeAttr(attributeName) 
$('em').removeAttr('title');

.removeAttr(attributeName, value)
$('em').removeAttr('title','hello,my friend');

prop()與removeProp() 獲取/移除元素屬性值狀態

• prop()可以抓取元素屬性值，可以是String、Number、Boolean
• radio.checked當點選/取消時的狀態使用prop()。
• attr()／remoceAttr()／prop()CodePen範例

.prop(propertyName) 
$('input').prop('disabled',false);
$('input').prop('checked',true);
$('input').removeProp('checked');

val() 取值

val() CodePen範例

<input type="text" value="some text">
<p></p>

var inputVal = $('input').val();
console.log(inputVal);
$('p').text("取出值為：" + inputVal);

//列印結果
取出值為：some text

二、CSS(獲取／設置CSS相關屬性)

.css() 更改CSS

以下為修改box1的css顏色

<div id="box1">1</div>

$('.box1').css("color","red");

height() 獲取本身高度

height()/innerHeight()/outerHeight() Codepen範例

獲取元素的當前計算高度
計算視窗高度，不包含margin.padding.border

.height()

$(window).height();  //視窗高度
$(document).height(); //整個網頁的高度

innerHeight() 獲取內部高度

height()/innerHeight()/outerHeight() Codepen範例

獲取元素的當前計算高度
計算視窗高度，包含padding，但不包含border.margin

ourterHeight() 獲取外部高度

height()/innerHeight()/outerHeight() Codepen範例

獲取元素的當前計算高度
計算視窗高度，包含padding.margin.border

width() 獲取本身寬度

width()/innerWidth()/outerWidth() Codepen範例

獲取元素的當前計算寬度
計算視窗高度，不包含margin.padding.border

.width()

$(window).width();  //視窗寬度
$(document).width(); //整個網頁的寬度

innerWidth() 獲取內部寬度

width()/innerWidth()/outerWidth() Codepen範例

獲取元素的當前計算寬度
計算視窗寬度，包含padding，但不包含border.margin

outerWidth() 獲取外部寬度

width()/innerWidth()/outerWidth() Codepen範例

[重點]說明Offset()與position()差異

在介紹offset()與position()之前先稍了解以下兩者的差別，
主要是差在「相對位置」的不同，參閱兩者範例就可以了解！

offset() - 只會以整個document、body或是說整著網站作為相對位置來抓取元素座標
Position() - 會以指定元素的層級開始往上尋找、找到第一個position為relative元素作為此元素的相對位置來抓取元素座標

offset() 獲取坐標

offset() Codepen範例

獲取元素的當前計算寬度
計算視窗寬度，包含padding.margin.border

1. 獲取或設置匹配元素當前坐標

<p>我要偵測p坐標</p>

$('p').offset();

2. 返回包含屬性top/left
   下方以codepen來說明，計算出top與left之坐標

$('p').offset().left;
$('p').offset().top;

以範例結果為
left: 8,
top: 125.875

3. 若要計算出bottom與right兩者的坐標，就要透過top+height/left+width來計算

//left+計算區塊的寬度加總(outerWidth)＝right坐標寬度
//計算結果 8+400=408
$(".offsetBlock").offset().left +$(".offsetBlock").outerWidth();

//top+計算區塊的寬度加總(outerHeight)＝bottom坐標寬度
//計算結果 125.875+66=191.875
$(".offsetBlock").offset().top + $(".offsetBlock").outerHeight();

以範例結果為
right: 408,
bottom: 191.875

position() 獲取坐標

position() Codepen範例

返回包含屬性top/left

1. 獲取或設置匹配元素當前坐標

<p>我要偵測p坐標</p>

$('p').position();

2. 返回包含屬性top/left
   下方以codepen來說明，計算出top與left之坐標

$('p').position().left;
$('p').position().top;

以範例結果為
left: 8,
top: 147.875

3. 若要計算出bottom與right兩者的坐標，就要透過top+height/left+width來計算

//left+計算區塊的寬度加總(outerWidth)＝right坐標寬度
//計算結果 8+400=408
$(".positionBlock").position().left +$(".positionBlock").outerWidth();

//top+計算區塊的寬度加總(outerHeight)＝bottom坐標寬度
//計算結果 125.875+66=191.875
$(".positionBlock").position().top + $(".positionBlock").outerHeight();

以範例結果為
right: 418,
bottom: 547.875

scrollLeft() 獲取元素滾動條當前水平X軸

scrollLeft()與scrollTop() CodePen範例

• 在捲動時取得滾動水平X值
• 滾動條如果位於最頂部或不可滾動時，數字為0

1. 使用chrome開發者工具監聽滾動數值

var scrollLeft = $(".demo").scrollLeft();
console.log(scrollLeft);

2. 可以直接給定滾動數值參數

$(".demo").scrollLeft(10);

scrollTop() 獲取元素滾動條當前垂直Y軸

scrollLeft()與scrollTop() CodePen範例

• 在捲動時取得滾動垂直Y值
• 滾動條如果位於最頂部或不可滾動時，數字為0

1. 使用chrome開發者工具監聽滾動數值

var scrollTop = $(".demo").scrollTop();
console.log(scrollTop);

2. 可以直接給定滾動數值參數

$(".demo").scrollTop(10);

三、Effects(動畫效果)

hide() 隠藏

.hide([duration] [, complete])

類似.css("display","none")效果

$('.box').hide();
$('.box').hide("slow");
$('.box').hide(1000);

show() 顯示

.show([duration] [, complete])

類似.css("display","block")效果

$('.box').show();
$('.box').show("slow");
$('.box').show(1000);

toggle() 切換顯示／隠藏

.toggle([duration] [,complete])

$('.box').toggle();
$('.box').toggle("slow");
$('.box').toggle(1000);

animate() CSS自定義動畫

範例
使用CSS樣式效果寫法
將平滑滾動添加到頁面錨點

• animate()主要是透過CSS樣式來產生動畫效果
• CSS樣式是使用DOM名稱(ex.fontSize)來設置，而非原來的CSS名稱(ex.font-size)
• 有關CSS樣式對應Dom屬性，可參考此份清單 MDN CSS屬性清單
• 因官方提供的動畫範例不多，w3school有一些樣式動畫範例可參考w3school jQuery animate()

.animate(properties [,duration] [,easing] [,complete])

animate()寫法
$(selector).animate({styles},duration,easing,callback)
//{styles}：放樣式
//duration：動畫持續速度，values可以填數值(ex.100,1000,5000)，以毫秒為單位，1000代表1秒、"slow"、"fast"
//easing：動畫效果，ex.swing(預設效果)/linear

$('.box').animate({
  minHeight:'200', 
  width:'300'
},1500,"linear")

fadeIn() 淡入動畫

fadeIn()／fadeOut()／fadeTo()／fadeToggle() Codepen範例

.fadeIn( [duration ] [, complete ] )

duration是指動畫持續時間，values可以填數值(ex.100,1000,5000)、"slow"、"fast"

$('.box1').fadeIn('slow');
$('.box1').fadeIn(800);

fadeOut() 淡出動畫

fadeIn()／fadeOut()／fadeTo()／fadeToggle() Codepen範例

.fadeOut([duration ] [,complete])

• duration是指動畫持續時間，values可以填數值(ex.100,1000,5000)、"slow"、"fast"

$('.box1').fadeOut('slow');
$('.box1').fadeOut(800);

fadeTo() 設定淡入淡出動畫

fadeIn()／fadeOut()／fadeTo()／fadeToggle() Codepen範例

.fadeTo(duration, opacity [,complete])

• duration是指動畫持續時間，values可以填數值(ex.100,1000,5000)、"slow"、"fast"
• opacity為透明度，數值為0~1之間的數字

$(".box2").fadeTo("fast", Math.random());
$('.box2').fadeTo('slow',0.33);
$('.box2').fadeTo(250,0.25);

fadeToggle() 切換淡入淡出動畫

設定淡入淡出來切換顯示/隠藏效果

fadeIn()／fadeOut()／fadeTo()／fadeToggle() Codepen範例

.fadeToggle([duration] [,easing] [,complete])

• duration是指動畫持續時間，values可以填數值(ex.100,1000,5000)、"slow"、"fast"
• easing使用那種動畫效果，ex.swing(預設效果)/linear，更多種動畫效果可參考這個網站easing函數速查表

$('.box1').fadeToggle('slow');
$('.box1').fadeToggle(800);

slideDown() 向下滑動效果

slideDown()／slideUp()／slideToggle() Codepen範例

.slideDown([duration] [, complete])

duration是指動畫持續時間，values可以填數值(ex.100,1000,5000)、"slow"、"fast"

$('.box1').slideDown('slow');
$('.box1').slideDown(800);

sliderUp() 向上滑動效果

slideDown()／slideUp()／slideToggle() Codepen範例

.slideUp([duration] [, complete])

duration是指動畫持續時間，values可以填數值(ex.100,1000,5000)、"slow"、"fast"

$('.box1').slideUp('slow');
$('.box1').slideUp(800);

sliderToggle() 滑動切換效果

slideDown()／slideUp()／slideToggle() Codepen範例

.slideToggle([duration] [, complete])

duration是指動畫持續時間，values可以填數值(ex.100,1000,5000)、"slow"、"fast"

$('.box1').slideToggle('slow');
$('.box1').slideToggle(800);

delay()

設置時間以延遲隊列中後續項目的執行。

.delay(duration [,queueName])

$('#foo').slideUp(300).delay(800).fadeIn(400);

finish()

停止當前正在運行的動畫，並刪除排隊的動畫，結束動畫，一切重來

$('.box').finish();

stop()

停止當前正在運行的動畫，並結束動畫，但不會刪除排隊的動畫

$('.box').stop();
$('.box').stop().slideToggle(1000);

四、Forms 表單事件

focus()與blur() 點擊/離開焦點時

focus()與blur() Codepen範例

blur()與focus()可以搭配應用，通常用在input焦點判斷上，實際可查看codepen範例

<input id="target" type="text" value="請輸入文字">

$("#target").on("focus", function () {
    //點選input文字消失事件
     console.log('進到焦點')
});
$("#target").on("blur", function () {
    //離開input時文字顯示事件
    console.log('離開焦點')
});

change() 更改

change() Codepen範例

- 此事件僅限於用在<input>／<textarea>／<select>元素
- 當input.textarea有輸入文字變更或是select選取狀態時

<input id="target" type="text" value="請輸入文字">

$('.input-target').on("change",function(){
  console.log('文字輪入有變更')
})
$('input[type='text']').change(function() {
  //也可以直接使用input[type='text']相關html屬性
});

submit() 提交

form表單簡單驗證欄位沒寫範例

五、event 事件

文件預載

Dom完全加載時執行，一般常見寫法如下

$(document).ready(function(){
    //html頁面加載後執行
})

但依據jQuery文件手冊提到從jQuery3.0開始，僅建議使用以下語法，其他語法雖仍然有效，但已棄用

$(function () {
  //html頁面加載後執行
});

resize() 偵測調整大小

resize()偵測尺寸
可以綁定當偵測瀏覽器寬度或高度時之事件

scroll() 滾動事件

可以綁定當偵測瀏覽器滾動時之事件

六、Manipulation>DOM Insertion,Inside(元素內插入新內容)

text() 抓取文字

text()與html()CodePen範例

1. 會抓取匹配元素中的內文，也包括他們的後代，但不包含html

//html
<p><b>Test</b> Paragraph.</p>
<p></p>

//找到第一個<p>的內文，也包含<b>裡面，結果為Test Paragraph.
var firstText = $('p').first().text(); 

//找到後，放入最後一個<p>裡面
$('p').last().text(firstText);

2. 注意與比較跟html()的不同，text()所獲取的是文字，這邊主要是理解觀念差別，一般並不會在text()裡面放入相關HTML標籤

//html
<p>Test Paragraph.</p>

$('p').text('<b>Some</b> new text.');//更換<p>裡面文字

//印出結果
'<b>Some</b> new text.' >>>>注意這是一段文字，是字符串而非為HTML

html() 抓取文字

text()與html()CodePen範例

1. html()是抓取元素的html內容

//html
<div class="demo-container">
  <div class="demo-box">Demonstration Box</div>
</div>

$('.demo-container').html()

//印出結果
<div class="demo-box">Demonstration Box</div>

2. 也可以抓取後重新設置元素的html內容

//html
<div class="demo-container">
  <div class="demo-box">Demonstration Box</div>
</div>

$('.demo-container').html('<p>All new content. <em>You bet!</em></p>');

//印出結果
<div class="demo-container">
  <p>All new content. <em>You bet!</em></p>
</div>

append()附加內容至元素最後

addend()CodePen範例

一、使用方式

.append(content[,content]) 
.append(function)

二、範例寫法

1. 將指定的內容(htmlString,Element)插入到元素的最後

//html
<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

$('.inner').append('<p>Test</p>');

//印出結果是讓你知道增加到那裡，實際結果可參考codepen
<div class="container">
  <div class="inner">
      Hello
      <p>Test</p>
  </div>
  <div class="inner">
      Goodbye
      <p>Test</p>
  </div>
</div>

2. 將指定的內容(Element)插入到元素的最後

//html
<div class="container">
  <div class="inner">Hello:</div>
</div>

$('.inner').append(document.createTextNode('我是小明'));

//印出結果
Hello:我是小明

3. 搬動選擇的元素，插入到目標容器之最後

//html
<h2>Greetings</h2> //原本在這裡
<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

$('.inner').append($('h2'));

//印出結果
<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
  <h2>Greetings</h2> //跑到這裡
</div>

appendTo() 附加內容至元素最後

append()與appendTo()方法最後執行的結果都是一樣
主要差別是在語意表達與程式撰寫時是顛倒過來的
例如：A.append(B)意思是將B放到A裡面的最後一個位置；A.appendTo(B)意思是將A放到B中的最後一個位置

1. 將指定的內容(htmlString,Element)插入到元素的最後

//html
<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

$('<p>Test</p>').appendTo('.inner'); //在這邊就可以看到與append()的差別

//印出結果是讓你知道增加到那裡，實際結果可參考codepen
<div class="container">
  <div class="inner">
      Hello
      <p>Test</p>
  </div>
  <div class="inner">
      Goodbye
      <p>Test</p>
  </div>
</div>

2. 搬動選擇的元素，插入到目標容器之最後

//html
<h2>Greetings</h2> //原本在這裡
<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

$('h2').appendTo($('.container')); ////在這邊就可以看到與append()的差別

//印出結果
<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
  <h2>Greetings</h2> //跑到這裡
</div>

prepend() 附加內容至元素最前

剛好與append()相反
prepend()CodePen範例

一、使用方式

.prepend(content[,content]) 
.prepend(function)

二、範例寫法

1. 將指定的內容(htmlString,Element)插入到元素的最後

//html
<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

$('.inner').prepend('<p>Test</p>');

//印出結果是讓你知道增加到那裡，實際結果可參考codepen
<div class="container">
  <div class="inner">
      <p>Test</p>
      Hello
  </div>
  <div class="inner">
      <p>Test</p>
      Goodbye
  </div>
</div>

2. 將指定的內容(Element)插入到元素的最後

//html
<div class="container">
  <div class="inner">大家好</div>
</div>

$('.inner').prepend(document.createTextNode('我是小明，'));

//印出結果
我是小明，大家好

3. 搬動選擇的元素，插入到目標容器之最後

//html
<h2>Greetings</h2> //原本在這裡
<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

$('.inner').prepend($('h2'));

//印出結果
<div class="container">
  <h2>Greetings</h2> //跑到這裡
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

prependTo() 附加內容至元素最前

prepend()與prependTo()方法最後執行的結果都是一樣
主要差別是在語意表達與程式撰寫時是顛倒過來的
例如：A.prepend(B)意思是將B放到A裡面的最前一個位置；A.prependTo(B)意思是將A放到B中的最前一個位置

1. 將指定的內容(htmlString,Element)插入到元素的最後

//html
<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

$('<p>Test</p>').prependTo('.inner'); //在這邊就可以看到與prepend()的差別

//印出結果是讓你知道增加到那裡，實際結果可參考codepen
<div class="container">
  <div class="inner">
      <p>Test</p>
      Hello
  </div>
  <div class="inner">
      <p>Test</p>
      Goodbye
  </div>
</div>

2. 搬動選擇的元素，插入到目標容器之最後

//html
<h2>Greetings</h2> //原本在這裡
<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

$('h2').prependTo($('.container')); //在這邊就可以看到與prepend()的差別

//印出結果
<div class="container">
  <h2>Greetings</h2> //跑到這裡
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

七、Traversing

even() 偶數

一、使用方式

.even() 
jQuery3.5支援，不能傳任何參數

二、範例寫法
找到該集合中的偶數，偶數計算從0開始編號

//這個範例假如<li>有六個，就會將偶數列增加背景顏色

$('li').even().css('background-color','red');

odd() 奇數

一、使用方式

.odd() 
jQuery3.5支援，不能傳任何參數

二、範例寫法
找到該集合中的奇數，奇數計算從1開始編號

//這個範例假如<li>有六個，就會將奇數列增加背景顏色

$('li').odd().css('background-color','red');

eq() 指定index

一、使用方式

eq(index)

將匹配元素指定index的位置(由0開始)，如果是負數，則從集合中的最後一個元素開始倒回去計數。

<ul>
  <li>list item 1</li> //基準0
  <li>list item 2</li>
  <li>list item 3</li> //eq(2)
  <li>list item 4</li> //eq(-2)
  <li>list item 5</li>
</ul>

//eq(2)＝＝＞結果為將item3背景設為紅色
$('li').eq(2).css('background-color', 'red');

//eq(-2)＝＝＞結果為將item4背景設為紅色
//說明：假如item1基準為0，往負值順序為-1,-2，從最後一個元素位置開始計算，也就是item5為eq(-1),item4就為eq(-2)
$('li').eq(2).css('background-color', 'red');

siblings()相鄰兄弟

一、使用方式

siblings(selector)

代表搜尋匹配元素的同胞元素

//html結構
<ul>
   <li>list item 1</li>
   <li>list item 2</li>
   <li class="third-item">list item 3</li>
   <li>list item 4</li>
   <li>list item 5</li>
</ul>

//請找到class為"third-item"，相鄰的li都會背景變成紅色
$('li.third-item').siblings().css('background-color', 'red');

再看一個例子

//html結構
<div><span>Hello</span></div>
<p class="selected">Hello Again</p>
<p>And Again</p>

//這個例子是請找到P元素，然後相鄰兄弟是.selected的class，然後背景變成黃色
$("p").siblings(".selected").css("background", "yellow");