Node.insertBefore()

Node.insertBefore() 方法在参考节点之前插入一个拥有指定父节点的子节点。如果给定的子节点是对文档中现有节点的引用,insertBefore() 会将其从当前位置移动到新位置(在将节点附加到其他节点之前,不需要从其父节点删除该节点)。

这意味着一个节点不能同时位于文档的两个点中。因此,如果节点已经有父节点,则首先删除该节点,然后将其插入到新位置。在将节点追加到新父节点之前,可以使用 Node.clonenode() 复制节点。注意,使用 cloneNode() 创建的节点副本不会自动与原始节点保持同步。

如果引用节点为 null,则将指定的节点添加到指定父节点的子节点列表的末尾。

如果给定的子节点是 DocumentFragment,那么 DocumentFragment 的全部内容将被移动到指定父节点的子节点列表中。

语法

var insertedNode = parentNode.insertBefore(newNode, referenceNode);
  • insertedNode 已经经过插入newNode的新的节点
  • parentNode 新插入节点的父节点
  • newNode 用于插入的节点
  • referenceNode newNode 将要插在这个节点之前

如果 referenceNode 为 nullnewNode 将被插入到子节点的末尾

referenceNode 引用节点不是可选参数——你必须显式传入一个 Node 或者 null。如果不提供节点或者传入无效值,在不同的浏览器中会有不同表现

返回值

函数返回被插入过的子节点;当 newNodeDocumentFragment 时,返回空 DocumentFragment

例子

示例 1

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

<script>
// 创建要插入的节点
var newNode = document.createElement("span");

// 获得父节点的引用
var parentDiv = document.getElementById("childElement").parentNode;

//实验一:referenceNode 存在 --> 正确返回
var sp2 = document.getElementById("childElement");
parentDiv.insertBefore(newNode, sp2);
//实验一结束

//实验二:referenceNode 为 undefined
var sp2 = undefined; // Not exist a node of id "childElement"
parentDiv.insertBefore(newNode, sp2); //隐式转换到节点类型
//实验二结束

//实验三:referenceNode 为字符类型的 "undefined"
var sp2 = "undefined"; //不存在id为"childElement"的referenceNode
parentDiv.insertBefore(newNode, sp2); // Generate "Type Error: Invalid Argument"
//实验三结束
</script>

示例 2

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

<script>
//创建一个新的、普通的<span>元素
var sp1 = document.createElement("span");

//插入节点之前,要获得节点的引用
var sp2 = document.getElementById("childElement");
//获得父节点的引用
var parentDiv = sp2.parentNode;

//在DOM中在sp2之前插入一个新元素
parentDiv.insertBefore(sp1, sp2);
</script>

没有 insertAfter()。不过,可以使用 insertBeforeNode.nextSibling 来模拟它。

在前一个例子中,可使用下面代码将 sp1 插入到 sp2 之后:

parentDiv.insertBefore(sp1, sp2.nextSibling);

如果 sp2 没有下一个节点,则它肯定是最后一个节点,则 sp2.nextSibling 返回 null,且 sp1 被插入到子节点列表的最后面(即 sp2 后面)。

示例 3

在第一个子元素的前面插入一个元素,可使用 firstChild 属性。

//插入节点之前,要获得节点的引用
var parentElement = document.getElementById('parentElement');
//获得第一个子节点的引用
var theFirstChild = parentElement.firstChild;

//创建新元素
var newElement = document.createElement("div");

//在第一个子节点之前插入新元素
parentElement.insertBefore(newElement, theFirstChild);

当元素没有首节点时,firstChild 返回 null。该元素仍然会被插入到父元素中,位于最后一个节点后面。又由于父元素没有第一个子节点,也没有最后一个子节点。 最终,新元素成为唯一的子元素。

浏览器兼容性

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
insertBeforeChrome Full support 1Edge Full support 12Firefox Full support 3IE Full support 9Opera Full support YesSafari Full support YesWebView Android Full support 1Chrome Android Full support 18Firefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android ?

Legend

Full support  
Full support
Compatibility unknown  
Compatibility unknown

规范

Specification Status Comment
DOM
Node.insertBefore
Living Standard Fixes errors in the insertion algorithm
DOM4
Node.insertBefore
Obsolete Describes the algorithm in more detail
Document Object Model (DOM) Level 3 Core Specification
Node.insertBefore
Obsolete No notable changes
Document Object Model (DOM) Level 2 Core Specification
Node.insertBefore
Obsolete No notable changes
Document Object Model (DOM) Level 1 Specification
Node.insertBefore
Obsolete Introduced

参见