angular.element 是 AngularJS 提供的 DOM 包裝入口。當頁面上已載入 jQuery 時,它會直接回傳 jQuery 物件;若沒有,則使用 AngularJS 內建的子集——JQLite。以下依功能分類整理其可用方法。
類別操作
addClass()
- 為每個匹配的元素添加指定的樣式類名。
removeClass()
- 移除集合中每個匹配元素上一個、多個或全部樣式類。
toggleClass()
- 在每個匹配元素上添加或刪除指定樣式類,取決於該類目前是否存在。
hasClass()
- 確定是否有任何一個匹配元素帶有指定的樣式類。
內容操作
html()
- 獲取集合中第一個匹配元素的 HTML 內容。
text()
- 取得匹配元素集合中每個元素的合併文字,包含其後代。
append()
- 在每個匹配元素內部的末尾處插入參數內容。
prepend()
- 將參數內容插入到每個匹配元素的前面(元素內部)。
after()
- 在匹配元素集合中每個元素後面插入內容,作為其兄弟節點。
empty()
- 從 DOM 中移除集合中匹配元素的所有子節點。
contents()
- 獲得匹配元素集合中每個元素的子節點,包括文字與註釋節點。
屬性操作
attr()
- 獲取匹配元素集合中第一個元素的屬性(attribute)值。
prop()
- 獲取匹配元素集中第一個元素的屬性(property)值。
removeAttr()
- 為匹配元素集合中的每個元素移除一個屬性。
css()
- 獲取匹配元素集合中第一個元素的樣式屬性值。
data()
- 在匹配元素上存儲任意相關數據。
removeData()
- 在元素上移除綁定的數據。
val()
- 獲取匹配元素集合中第一個元素的當前值。
實務上要留意 attr() 與 prop() 的差異:前者操作 HTML 屬性字串,後者操作元素物件的當前狀態屬性。處理 checked、selected、disabled 這類會隨使用者互動變化的狀態時,應使用 prop()。
DOM 遍歷
children()
- 獲得匹配元素集合中每個元素的子元素,可用選擇器篩選。
find()
- 透過選擇器過濾,得到當前匹配元素集合中每個元素的後代。
next()
- 取得每個元素緊鄰在後的同輩元素集合;若提供選擇器,只有符合條件的才會返回。
parent()
- 取得匹配元素集合中每個元素的父元素,可選提供選擇器。
eq()
- 將匹配元素的集合縮減為指定索引的那一個元素。
clone()
- 創建一個匹配元素集合的深度拷貝副本。
事件操作
on()
- 在選定的元素上綁定一個或多個事件處理函數。
off()
- 移除一個事件處理函數。
one()
- 為元素的事件添加處理函數,處理函數在每個元素上每種事件類型最多執行一次。
bind()
- 為一個元素綁定一個事件處理程序(JQLite 中的別名形式)。
unbind()
- 從元素上刪除一個先前附加的事件處理程序。
triggerHandler()
- 為一個事件執行附加到元素的所有處理程序。
DOM 移除與替換
remove()
- 將匹配元素集合從 DOM 中刪除,同時移除元素上的事件與數據。
detach()
- 從 DOM 中去掉所有匹配的元素,但保留其數據與事件。
replaceWith()
- 用提供的內容替換集合中所有匹配的元素,並返回被刪除元素的集合。
wrap()
- 在每個匹配的元素外層包上一個 HTML 元素。
remove() 與 detach() 的差別值得記住:若你打算稍後把元素插回頁面並希望事件仍然有效,必須用 detach()。
就緒狀態
ready()
- 當 DOM 準備就緒時,指定一個函數來執行。
在 AngularJS 中,這個方法通常不需要——初始化邏輯應該放在 controller 或 directive 的 link 函式中,由框架保證時序。
使用上的建議
JQLite 只實作了上述这些方法,並不包含動畫、Ajax 等完整 jQuery 功能。因此在 AngularJS 專案中的實務準則是:
- 能用 AngularJS 內建的 ng-* 指令解決的,不要用
angular.element。直接操作 DOM 會繞過資料綁定與 digest 流程。
- 確實需要操作 DOM 時,應寫在 directive 的 link 函式中,而不是 controller 裡。
- 修改 scope 資料後記得呼叫
$apply()(或改用 $timeout 等服務),否則畫面不會更新。
- 若專案已載入 jQuery,
angular.element 會自動改用完整 jQuery,行為差異要注意。
一句話總結:angular.element 是逃生口,不是主要工具。它的存在是為了讓你在框架無法覆蓋的邊角場景裡有個熟悉的介面可用。