Selection

例項屬性

Selection.anchorNode 只讀

返回選擇開始所在的 Node。如果文件中從未存在過選擇（例如，一個從未被點選過的 iframe），則可能返回 null。

Selection.anchorOffset 只讀

返回一個數字，表示選擇錨點在 anchorNode 內的偏移量。如果 anchorNode 是一個文字節點，則表示錨點之前 anchorNode 中的字元數。如果 anchorNode 是一個元素，則表示錨點之前 anchorNode 的子節點數。

Selection.direction 只讀

一個描述當前選擇方向的字串。

Selection.focusNode 只讀

返回選擇結束所在的 Node。如果文件中從未存在過選擇（例如，一個從未被點選過的 iframe），則可能返回 null。

Selection.focusOffset 只讀

返回一個數字，表示選擇焦點在 focusNode 內的偏移量。如果 focusNode 是一個文字節點，則表示焦點之前 focusNode 中的字元數。如果 focusNode 是一個元素，則表示焦點之前 focusNode 的子節點數。

Selection.isCollapsed 只讀

返回一個布林值，指示選擇的起始點和結束點是否在同一位置。

Selection.rangeCount 只讀

返回選擇中範圍的數量。

Selection.type 只讀

一個描述當前選擇型別的字串。

例項方法

Selection.addRange()

一個將被新增到選擇中的 Range 物件。

Selection.collapse()

將當前選擇摺疊到單個點。

Selection.collapseToEnd()

將選擇摺疊到選擇中最後一個範圍的末尾。

Selection.collapseToStart()

將選擇摺疊到選擇中第一個範圍的開頭。

Selection.containsNode()

指示某個節點是否是選擇的一部分。

Selection.deleteFromDocument()

從文件中刪除選擇的內容。

Selection.empty()

從選擇中移除所有範圍，將 anchorNode 和 focusNode 屬性設定為 null，並且不選擇任何內容。

Selection.extend()

將選擇的焦點移動到指定點。

Selection.getComposedRanges()

返回一個 StaticRange 物件陣列，每個物件代表一個可能跨越 Shadow DOM 邊界的選擇。

Selection.getRangeAt()

返回一個 Range 物件，表示當前選擇的一個範圍。

Selection.modify()

更改當前選擇。

Selection.removeRange()

從選擇中移除一個範圍。

Selection.removeAllRanges()

從選擇中移除所有範圍。

Selection.selectAllChildren()

將指定節點的**所有**子節點新增到選擇中。

Selection.setBaseAndExtent()

將選擇設定為一個範圍，該範圍包含兩個指定 DOM 節點的所有或部分內容，以及它們之間的任何內容。

Selection.setPosition()

將當前選擇摺疊到單個點。

Selection.toString()

返回當前由 selection 物件表示的字串，即當前選擇的文字。

注意

Selection 的字串表示

呼叫 Selection.toString() 方法會返回選擇中包含的文字，例如：

const selObj = window.getSelection();
window.alert(selObj);

請注意，將 selection 物件作為 window.alert 的引數會呼叫該物件的 toString 方法。

選擇中的多個範圍

selection 物件代表使用者選擇的 Range。通常，它只包含一個範圍，訪問方式如下：

const selObj = window.getSelection();
const range = selObj.getRangeAt(0);

• selObj 是一個 Selection 物件
• range 是一個 Range 物件

正如 Selection API 規範所指出的，Selection API 最初由 Netscape 建立，並支援多個範圍（例如，允許使用者從 <table> 中選擇一列）。然而，除了 Gecko 之外的瀏覽器並未實現多範圍支援，並且該規範還要求 selection 始終只有一個範圍。

Selection 和輸入焦點

Selection 和輸入焦點（由 Document.activeElement 指示）之間存在複雜的關係，具體取決於瀏覽器。在跨瀏覽器相容的程式碼中，最好將它們分開處理。

Safari 和 Chrome（與 Firefox 不同）目前在以程式設計方式修改 selection 時會聚焦包含 selection 的元素；這未來可能會改變（請參閱 W3C bug 14383 和 WebKit bug 38696）。

Selection API 在編輯主機焦點更改方面的行為

Selection API 具有一種常見的行為（即瀏覽器之間共享），它規定了在呼叫某些方法後，編輯主機的焦點行為如何變化。

行為如下：

1. 如果之前的 selection 在編輯主機之外，則編輯主機獲得焦點。
2. 呼叫 Selection API 方法，導致建立了一個新的 selection，其 selection 範圍在編輯主機內部。
3. 焦點然後會轉移到編輯主機。

上述行為適用於使用以下方法進行的 selection：

• Selection.collapse()
• Selection.collapseToStart()
• Selection.collapseToEnd()
• Selection.extend()
• Selection.selectAllChildren()
• Selection.addRange()
• Selection.setBaseAndExtent()

以及使用以下方法修改 Range 時：

• Range.setStart()
• Range.setEnd()
• Range.setStartBefore()
• Range.setStartAfter()
• Range.setEndBefore()
• Range.setEndAfter()
• Range.collapse()
• Range.selectNode()
• Range.selectNodeContents()

術語表

本節中使用的其他關鍵術語。

anchor (錨點)

Selection 的錨點是選擇的起點。使用滑鼠進行選擇時，錨點是滑鼠按鈕最初按下的文件位置。當用戶使用滑鼠或鍵盤更改選擇時，錨點不會移動。

editing host (編輯主機)

可編輯元素（例如，設定為 contenteditable 的 HTML 元素，或 designMode 啟用的文件的 HTML 子項）。

focus of a selection (selection 的焦點)

Selection 的焦點是選擇的終點。使用滑鼠進行選擇時，焦點是釋放滑鼠按鈕的文件位置。當用戶使用滑鼠或鍵盤更改選擇時，焦點是移動的選擇的末尾。

注意：這與文件的焦點元素不同，後者由 document.activeElement 返回。

range

範圍 (range) 是文件的連續部分。一個範圍可以包含完整的節點，也可以包含節點的一部分（例如文字節點的一部分）。使用者通常一次只選擇一個範圍，但使用者也可以選擇多個範圍（例如，透過使用 Control 鍵）。可以透過 Selection 物件獲取一個範圍，作為 range 物件。Range 物件也可以透過 DOM 建立，並以程式設計方式新增到 selection 中或從 selection 中移除。

規範

瀏覽器相容性

另見

• Window.getSelection、Document.getSelection、Range
• 與 Selection 相關的事件：selectionchange 和 selectstart
• HTML 輸入提供了更簡單的輔助 API 來處理 selection（請參閱 HTMLInputElement.setSelectionRange()）。
• Document.activeElement、HTMLElement.focus 和 HTMLElement.blur