---
title: Document.createElement()
slug: Web/API/Document/createElement
tags:
  - API
  - DOM
  - Document
  - 参考
  - 方法
translation_of: Web/API/Document/createElement
---
<div>{{APIRef("DOM")}}</div>

<p><span class="seoSummary">在 <a href="/zh-CN/docs/Web/HTML">HTML</a> 文档中,<strong><code>Document.createElement()</code></strong> 方法用于创建一个由标签名称 <var>tagName</var> 指定的 HTML 元素。如果用户代理无法识别 <var>tagName</var>,则会生成一个未知 HTML 元素 {{domxref("HTMLUnknownElement")}}。</span></p>

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

<pre class="syntaxbox notranslate">var <var>element</var> = <var>document</var>.createElement(<var>tagName</var>[, <var>options</var>]);
</pre>

<h3 id="参数">参数</h3>

<dl>
 <dt><var>tagName</var></dt>
 <dd>指定要创建元素类型的字符串,创建元素时的 {{domxref("Node.nodeName", "nodeName")}} 使用 <code>tagName</code> 的值为初始化,该方法不允许使用限定名称(如:"html:a"),在 HTML 文档上调用 <code>createElement()</code> 方法创建元素之前会将<code>tagName</code> 转化成小写,在 Firefox、Opera 和 Chrome 内核中,<code>createElement(null)</code> 等同于 <code>createElement("null")</code></dd>
 <dt><var>options</var>{{optional_inline}}</dt>
 <dd>一个可选的参数 <code>ElementCreationOptions</code> 是包含一个属性名为 <code>is</code> 的对象,该对象的值是用 <code>customElements.define()</code> 方法定义过的一个自定义元素的标签名。为了向前兼容较老版本的 <a href="https://www.w3.org/TR/custom-elements/">Custom Elements specification</a>, 有一些浏览器会允许你传一个值为自定义元素的标签名的字符串作为该参数的值。可以参考本页下方的 <a href="#web_component_示例">Web component 示例</a> Google 的 <a href="https://developers.google.com/web/fundamentals/primers/customelements/#extendhtml">Extending native HTML elements</a> 文档仔细了解如何使用该参数。</dd>
</dl>

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

<p>新建的元素({{domxref("Element")}})。</p>

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

<h3 id="HTML">HTML</h3>

<p>创建一个新的 <code>&lt;div&gt;</code> 并且插入到ID为“<code>div1</code>”的元素前。</p>

<pre class="brush:html notranslate">&lt;!DOCTYPE html&gt;
&lt;html&gt;
&lt;head&gt;
  &lt;title&gt;||Working with elements||&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
  &lt;div id="div1"&gt;The text above has been created dynamically.&lt;/div&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>

<h3 id="JavaScript">JavaScript</h3>

<pre class="brush: js notranslate">document.body.onload = addElement;

function addElement () {
  // 创建一个新的 div 元素
  let newDiv = document.createElement("div");
  // 给它一些内容
  let newContent = document.createTextNode("Hi there and greetings!");
  // 添加文本节点 到这个新的 div 元素
  newDiv.appendChild(newContent);

  // 将这个新的元素和它的文本添加到 DOM 中
  let currentDiv = document.getElementById("div1");
  document.body.insertBefore(newDiv, currentDiv);
}
</pre>

<p>{{EmbedLiveSample("Basic_example", 500, 50)}}</p>

<h3 id="Web_component_示例">Web component 示例</h3>

<p>以下示例片段取自我们的 expanding-list-web-component 示例(实时查看)。 在这个案例中, 我们的自定义元素继承了以 {{htmlelement("ul")}} 元素为代表的 {{domxref("HTMLUListElement")}}.</p>

<pre class="brush: js notranslate">// 为新元素创建一个类
class ExpandingList extends HTMLUListElement {
  constructor() {
    // Always call super first in constructor
    super();

    // constructor definition left out for brevity
    ...
  }
}

// 定义新元素
customElements.define('expanding-list', ExpandingList, { extends: "ul" });
</pre>

<p>如果我们想以函数的方式创建此元素的实例,则可以使用以下方式调用:</p>

<pre class="brush: js notranslate">let expandingList = document.createElement('ul', { is : 'expanding-list' })</pre>

<p>新元素将被赋予<code>is</code>属性,其值为自定义元素的标签名称。</p>

<div class="note">
<p><strong>Note</strong>: 为了兼容之前版本的 <a href="https://www.w3.org/TR/custom-elements/">Custom Elements specification</a> 规范,某些浏览器将允许您在此处传递字符串而不是对象,其中字符串的值是自定义元素的标记名。</p>
</div>

<h2 id="注意">注意</h2>

<ul>
 <li>在一个 <a href="/zh-CN/docs/Mozilla/Tech/XUL">XUL</a> 文档中,该方法创建指定的 XUL 元素。在其他文档中,它创建一个命名空间 URI 为 null 的元素,这时,新元素会继承文档的命名空间。</li>
 <li>若要显式指定元素的命名空间 URI,请使用 <a href="/zh-CN/docs/Web/API/Document/createElementNS"><code>document.createElementNS()</code></a>。</li>
 <li>当在一个被标记为HTML文档的文档对象上执行时,createElement()优先将参数转换为小写。</li>
 <li>当创建一个带限制条件的元素时,请使用{{ domxref("document.createElementNS()") }}。</li>
 <li>Gecko 2.0{{ geckoRelease("2.0") }}之前,quirks模式下tagName可以包含尖括号(&lt;和&gt;);从Gecko2.0开始,该方法在quirks模式和标准模式下表现一致。</li>
 <li>从Gecko19.0{{ geckoRelease("19.0") }}开始, <code>createElement(null)</code> 和 <code>createElement("null")</code> 相同。Opera 也会将 null 字符串化,但是 Chrome 和 IE 都会抛出错误。</li>
 <li>从Gecko22.0{{geckoRelease("22.0")}}开始,当参数为"bgsounds", "multicol", 或"image"时, <code>createElement()</code> 不再使用 {{domxref("HTMLSpanElement")}} 接口, 参数为 "bgsound" 和 "multicol" 时,使用 <code>HTMLUnknownElement</code> ,为“image”时使用{{domxref("HTMLElement")}} <code>HTMLElement</code>。</li>
 <li><code>createElement</code> 的Gecko实现不遵循XUL和XHTML的DOM说明文档: 创建元素的<code>localName</code>和<code>namespaceURI不会被设置为null</code>. 更多细节详见 {{Bug(280692)}}。</li>
</ul>

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

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">规范</th>
   <th scope="col">状态</th>
   <th scope="col">备注</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>{{SpecName('DOM WHATWG', "#dom-document-createelement", "Document.createElement")}}</td>
   <td>{{Spec2('DOM WHATWG')}}</td>
   <td></td>
  </tr>
 </tbody>
</table>

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



<p>{{Compat("api.Document.createElement")}}</p>

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

<ul>
 <li>{{domxref("Node.removeChild()")}}</li>
 <li>{{domxref("Node.replaceChild()")}}</li>
 <li>{{domxref("Node.appendChild()")}}</li>
 <li>{{domxref("Node.insertBefore()")}}</li>
 <li>{{domxref("Node.hasChildNodes()")}}</li>
 <li>{{domxref("document.createElementNS()")}} — 在创建元素时,明确指定元素的命名空间 URI。</li>
</ul>