path: root/files/zh-cn/web/api/node/insertbefore/index.html

---
title: Node.insertBefore()
slug: Web/API/Node/insertBefore
tags:
  - API
  - DOM
  - Method
  - Node
  - 参考
  - 方法
  - 节点
translation_of: Web/API/Node/insertBefore
---
<div>{{APIRef("DOM")}}</div>

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

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

<p>如果引用节点为 <code>null</code>，则将指定的节点添加到指定父节点的子节点列表的末尾。</p>

<p>如果给定的子节点是 {{domxref("DocumentFragment")}}，那么 <code>DocumentFragment</code> 的全部内容将被移动到指定父节点的子节点列表中。</p>

<h2 id="语法">语法</h2>

<pre class="brush: js notranslate">var <em>insertedNode</em> = <em>parentNode</em>.insertBefore(<em>newNode</em>, <em>referenceNode</em>);
</pre>

<ul>
 <li><code>insertedNode</code> 被插入节点(newNode)</li>
 <li><code>parentNode</code> 新插入节点的父节点</li>
 <li><code>newNode</code> 用于插入的节点</li>
 <li><code>referenceNode</code> <code>newNode</code> 将要插在这个节点之前</li>
</ul>

<p>如果 <code>referenceNode</code> 为 <code>null</code> 则 <code>newNode</code> 将被插入到子节点的末尾<em>。</em></p>

<div class="note">
<p><em><code>referenceNode</code></em> 引用节点<strong>不是</strong>可选参数——你必须显式传入一个 <code>Node</code> 或者 <code>null</code>。如果不提供节点或者传入无效值，在不同的浏览器中会有<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=119489">不同</a>的<a href="https://code.google.com/p/chromium/issues/detail?id=419780">表现</a>。</p>
</div>

<h2 id="返回值">返回值</h2>

<p>函数返回被插入过的子节点；当 <code>newNode</code> 是 {{domxref("DocumentFragment")}} 时，返回空 {{domxref("DocumentFragment")}}。</p>

<h2 id="例子">例子</h2>

<h3 id="示例_1">示例 1</h3>

<pre class="brush: js notranslate">&lt;div id="parentElement"&gt;
   &lt;span id="childElement"&gt;foo bar&lt;/span&gt;
&lt;/div&gt;

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

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

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

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

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

<h3 id="示例_2">示例 2</h3>

<pre class="brush: html notranslate">&lt;div id="parentElement"&gt;
  &lt;span id="childElement"&gt;foo bar&lt;/span&gt;
&lt;/div&gt;

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

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

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

<p>没有 <code>insertAfter()</code>。不过，可以使用 <code>insertBefore</code> 和 {{domxref("Node.nextSibling")}} 来模拟它。</p>

<p>在前一个例子中，可使用下面代码将 <code>sp1</code> 插入到 <code>sp2</code> 之后：</p>

<pre class="brush: js notranslate"><code>parentDiv.insertBefore(sp1, sp2.nextSibling);</code></pre>

<p>如果 <code>sp2</code> 没有下一个节点，则它肯定是最后一个节点，则 <code>sp2.nextSibling</code> 返回 <code>null</code>，且 <code>sp1</code> 被插入到子节点列表的最后面（即 <code>sp2</code> 后面）。</p>

<h3 id="Example2" name="Example2">示例 3</h3>

<p>在第一个子元素的前面插入一个元素，可使用 <a href="/en-US/docs/DOM/Node.firstChild" title="Node.firstChild">firstChild</a> 属性。</p>

<pre class="brush:js notranslate">//插入节点之前，要获得节点的引用
var parentElement = document.getElementById('parentElement');
//获得第一个子节点的引用
var theFirstChild = parentElement.firstChild;

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

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

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

<h2 id="Browser_Compatibility" name="Browser_Compatibility">浏览器兼容性</h2>



<p>{{Compat("api.Node.insertBefore")}}</p>

<h2 id="规范">规范</h2>

<table class="spectable standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('DOM WHATWG','#dom-node-insertbefore','Node.insertBefore')}}</td>
   <td>{{Spec2('DOM WHATWG')}}</td>
   <td>Fixes errors in the insertion algorithm</td>
  </tr>
  <tr>
   <td>{{SpecName('DOM4','#dom-node-insertbefore','Node.insertBefore')}}</td>
   <td>{{Spec2('DOM4')}}</td>
   <td>Describes the algorithm in more detail</td>
  </tr>
  <tr>
   <td>{{SpecName('DOM3 Core','core.html#ID-952280727','Node.insertBefore')}}</td>
   <td>{{Spec2('DOM3 Core')}}</td>
   <td>No notable changes</td>
  </tr>
  <tr>
   <td>{{SpecName('DOM2 Core','core.html#ID-952280727','Node.insertBefore')}}</td>
   <td>{{Spec2('DOM2 Core')}}</td>
   <td>No notable changes</td>
  </tr>
  <tr>
   <td>{{SpecName('DOM1','level-one-core.html#method-insertBefore','Node.insertBefore')}}</td>
   <td>{{Spec2('DOM1')}}</td>
   <td>Introduced</td>
  </tr>
 </tbody>
</table>

<h2 id="参见">参见</h2>

<ul>
 <li>{{domxref("Node.removeChild()")}}</li>
 <li>{{domxref("Node.replaceChild()")}}</li>
 <li>{{domxref("Node.appendChild()")}}</li>
 <li>{{domxref("Node.hasChildNodes()")}}</li>
 <li>{{domxref("Element.insertAdjacentElement()")}}</li>
 <li>{{domxref("ParentNode.prepend()")}}</li>
</ul>