Range 對象表示文檔中的連續(xù)范圍。
XML DOM - Range 對象
Range 對象
Range 對象表示文檔的連續(xù)范圍區(qū)域,如用戶在瀏覽器窗口中用鼠標拖動選中的區(qū)域。
如果一個實現(xiàn)支持 Range 模塊,那么 Document 對象就定義了 createRange() 方法,調(diào)用它可創(chuàng)建新的 Range 對象。
注意:IE 定義了不兼容的 Document.createRange() 方法,它返回的對象與 Rang 接口相似,但不兼容。
Range 接口為指定文檔“選中”的區(qū)域定義了大量的方法,此外還有幾個方法可以用于在選中的區(qū)域中進行剪切和粘貼類型的操作。
Range 接口的屬性提供了獲取范圍的邊界節(jié)點和偏移量的方法。它的方法提供了設置范圍邊界的方法。注意,范圍的邊界可以設置為 Document 或 DocumentFragment 對象中的節(jié)點。一旦定義了范圍的邊界點,就可以使用 deleteContents()、extractContents()、cloneContents() 和 insertNode() 方法實現(xiàn)剪切、復制和粘貼的操作。
當通過插入或刪除操作改變了文檔時,表示文檔一部分的所有 Range 對象都將改變(如果必要的話),以便使它們的邊界點保持有效,并且讓它們(盡可能接近地)表示同樣的文檔內(nèi)容。
術(shù)語:范圍、邊界點和偏移量
一個范圍具有兩個邊界點,即一個開始點和一個結(jié)束點。每個邊界點由一個節(jié)點和那個節(jié)點的偏移量指定。該節(jié)點通常是 Element 節(jié)點、Document 節(jié)點或 Text 節(jié)點。對于 Element 節(jié)點和 Document 節(jié)點,偏移量指該節(jié)點的子節(jié)點。偏移量為 0,說明邊界點位于該節(jié)點的第一個子節(jié)點之前。偏移量為 1,說明邊界點位于該節(jié)點的第一個子節(jié)點之后,第二個子節(jié)點之前。但如果邊界節(jié)點是 Text 節(jié)點,偏移量則指的是文本中兩個字符之間的位置。
Range 對象的常量
這些常量指定了如何比較 Range 對象的邊界點。
它們是 compareBoundaryPoints() 方法的 how參數(shù)的合法值:
常量 | 描述 |
---|---|
START_TO_START | 用指定范圍的開始點與當前范圍的開始點進行比較。 |
START_TO_END | 用指定范圍的開始點與當前范圍的結(jié)束點進行比較。 |
END_TO_END | 用指定范圍的結(jié)束點與當前范圍的結(jié)束點進行比較。 |
END_TO_START | 用指定范圍的結(jié)束點與當前范圍的開始點進行比較。 |
Range 對象的屬性
注意:所有屬性都是只讀的,不能通過設置這些屬性改變范圍的開始點和結(jié)束點,必須調(diào)用 setEnd() 方法和 setStart() 方法實現(xiàn)這一點。
注意:調(diào)用 detach() 方法后,對這些屬性的任何讀操作都會拋出代碼為 INVALID_STATE_ERR 的 DOMException 異常。
屬性 | 描述 |
---|---|
collapsed | 如果范圍的開始點和結(jié)束點在文檔的同一位置,則為 true,即范圍是空的,或折疊的。 |
commonAncestorContainer | 范圍的開始點和結(jié)束點的(即它們的祖先節(jié)點)、嵌套最深的 Document 節(jié)點。 |
endContainer | 包含范圍的結(jié)束點的 Document 節(jié)點。 |
endOffset | endContainer 中的結(jié)束點位置。 |
startContainer | 包含范圍的開始點的 Document 節(jié)點。 |
startOffset | startContainer 中的開始點位置。 |
Range 對象的方法
注意:如果調(diào)用了范圍的 detach() 方法,那么接下來調(diào)用 Range 對象的任何方法都會拋出代碼為 INVALID_STATE_ERR 的 DOMException 異常。
方法 | 描述 |
---|---|
cloneContents() | 返回新的 DocumentFragment 對象,它包含該范圍表示的文檔區(qū)域的副本。 |
cloneRange() | 創(chuàng)建一個新的 Range 對象,表示與當前的 Range 對象相同的文檔區(qū)域。 |
collapse() | 折疊該范圍,使它的邊界點重合。 |
compareBoundaryPoints() | 比較指定范圍的邊界點和當前范圍的邊界點,根據(jù)它們的順序返回 -1、0 和 1。比較哪個邊界點由它的第一個參數(shù)指定,它的值必須是前面定義的常量之一。 |
deleteContents() | 刪除當前 Range 對象表示的文檔區(qū)域。 |
detach() | 通知實現(xiàn)不再使用當前的范圍,可以停止跟蹤。如果調(diào)用了范圍的這個方法,那么接下來調(diào)用的該范圍任何方法都會拋出代碼為 INVALID_STATE_ERR 的 DOMException 異常。 |
extractContents() | 刪除當前范圍表示的文檔區(qū)域,并且以 DocumentFragment 對象的形式返回那個區(qū)域的內(nèi)容。該方法和 cloneContents() 方法與 deleteContents() 方法的組合很相似。 |
insertNode() | 把指定的節(jié)點插入文檔范圍的開始點。 |
selectNode() | 設置該范圍的邊界點,使它包含指定的節(jié)點和它的所有子孫節(jié)點。 |
selectNodeContents() | 設置該范圍的邊界點,使它包含指定節(jié)點的子孫節(jié)點,但不包含指定的節(jié)點本身。 |
setEnd() | 把該范圍的結(jié)束點設置為指定的節(jié)點和偏移量。 |
setEndAfter() | 把該范圍的結(jié)束點設置為緊鄰指定節(jié)點的節(jié)點之后。 |
setEndBefore() | 把該范圍的結(jié)束點設置為緊鄰指定節(jié)點之前。 |
setStart() | 把該范圍的開始點設置為指定的節(jié)點中的指定偏移量。 |
setStartAfter() | 把該范圍的開始點設置為緊鄰指定節(jié)點的節(jié)點之后。 |
setStartBefore() | 把該范圍的開始點設置為緊鄰指定節(jié)點之前。 |
surroundContents() | 把指定的節(jié)點插入文檔范圍的開始點,然后重定范圍中的所有節(jié)點的父節(jié)點,使它們成為新插入的節(jié)點的子孫節(jié)點。 |
toString() | 返回該范圍表示的文檔區(qū)域的純文本內(nèi)容。 |