节点：insertBefore() 方法

insertBefore() 是 Node 接口的一个方法，它在指定父节点的子节点列表中，将一个节点插入到参考节点之前。

如果给定的节点已存在于文档中，则 insertBefore() 会将其从当前位置移动到新位置。（也就是说，在将其追加到指定的新父节点之前，它将自动从其现有父节点中删除。）

这意味着一个节点不能同时存在于文档的两个位置。

注意：Node.cloneNode() 可用于在将节点追加到新父节点下之前创建该节点的副本。请注意，使用 cloneNode() 创建的副本不会自动保持同步。

如果给定的子节点是 DocumentFragment，则 DocumentFragment 的所有内容都会移动到指定父节点的子节点列表中。

语法

js
insertBefore(newNode, referenceNode)

参数

newNode

要插入的节点。

referenceNode

newNode 要插入到的节点之前。如果此值为 null，则 newNode 将插入到节点子节点的末尾。

注意：referenceNode 不是可选参数。您必须显式传递一个 Node 或 null。如果未提供或传递无效值，则在不同的浏览器版本中可能会表现不同。

返回值

返回添加的子节点（除非 newNode 是 DocumentFragment，在这种情况下，将返回空的 DocumentFragment）。

异常

插入前的有效性

示例

示例 1

html
<div id="parentElement">
  <span id="childElement">foo bar</span>
</div>

<script>
  // Create the new node to insert
  const newNode = document.createElement("span");

  // Get a reference to the parent node
  const parentDiv = document.getElementById("childElement").parentNode;

  // Begin test case [ 1 ] : Existing childElement (all works correctly)
  let sp2 = document.getElementById("childElement");
  parentDiv.insertBefore(newNode, sp2);
  // End test case [ 1 ]

  // Begin test case [ 2 ] : childElement is of Type undefined
  sp2 = undefined; // Non-existent node of id "childElement"
  parentDiv.insertBefore(newNode, sp2); // Implicit dynamic cast to type Node
  // End test case [ 2 ]

  // Begin test case [ 3 ] : childElement is of Type "undefined" (string)
  sp2 = "undefined"; // Non-existent node of id "childElement"
  parentDiv.insertBefore(newNode, sp2); // Generates "Type Error: Invalid Argument"
  // End test case [ 3 ]
</script>

示例 2

html
<div id="parentElement">
  <span id="childElement">foo bar</span>
</div>

<script>
  // Create a new, plain <span> element
  let sp1 = document.createElement("span");

  // Get the reference element
  let sp2 = document.getElementById("childElement");
  // Get the parent element
  let parentDiv = sp2.parentNode;

  // Insert the new element into before sp2
  parentDiv.insertBefore(sp1, sp2);
</script>

注意：没有 insertAfter() 方法。可以通过将 insertBefore 方法与 Node.nextSibling 结合使用来模拟它。

在前面的示例中，可以使用以下方法将 sp1 插入到 sp2 之后：

js
parentDiv.insertBefore(sp1, sp2.nextSibling);

如果 sp2 没有下一个兄弟节点，则它必须是最后一个子节点 — sp2.nextSibling 返回 null，并且 sp1 将插入到子节点列表的末尾（紧随 sp2 之后）。

示例 3

使用 firstChild 属性在第一个子元素之前插入一个元素。

js
// Get the parent element
let parentElement = document.getElementById("parentElement");
// Get the parent's first child
let theFirstChild = parentElement.firstChild;

// Create a new element
let newElement = document.createElement("div");

// Insert the new element before the first child
parentElement.insertBefore(newElement, theFirstChild);

当元素没有第一个子元素时，firstChild 为 null。该元素仍将附加到父元素，位于最后一个子元素之后。

由于父元素没有第一个子元素，因此它也没有最后一个子元素。因此，新插入的元素是唯一的元素。

规范

规范
DOM 标准
# dom-node-insertbefore

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。

另请参阅