initial commit

1 files changed, 168 insertions, 0 deletions

diff --git a/files/zh-cn/web/api/element/attachshadow/index.html b/files/zh-cn/web/api/element/attachshadow/index.html
new file mode 100644
index 0000000000..fa1389c4e1
--- /dev/null
+++ b/files/zh-cn/web/api/element/attachshadow/index.html
@@ -0,0 +1,168 @@
+---
+title: Element.attachShadow()
+slug: Web/API/Element/attachShadow
+tags:
+  - API
+  - 元素
+  - 参考
+  - 方法
+translation_of: Web/API/Element/attachShadow
+---
+<p>{{APIRef('Shadow DOM')}}</p>
+
+<p><strong><code>Element.attachShadow()</code></strong> 方法给指定的元素挂载一个Shadow DOM，并且返回对 <code><a href="/zh-CN/docs/Web/API/ShadowRoot">ShadowRoot</a></code> 的引用。</p>
+
+<h2 id="可以被挂载的shadow_DOM元素">可以被挂载的shadow DOM元素</h2>
+
+<p>要注意的是，不是每一种类型的元素都可以附加到shadow root（影子根）下面。出于安全考虑，一些元素不能使用 shadow DOM（例如{{htmlelement("a")}}），以及许多其他的元素。下面是一个<strong>可以</strong>挂载 shadow root 的元素列表：</p>
+
+<ul>
+ <li>任何带有<a href="https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name">有效的名称</a>且可独立存在的（autonomous）自定义元素</li>
+ <li>{{htmlelement("article")}}</li>
+ <li>{{htmlelement("aside")}}</li>
+ <li>{{htmlelement("blockquote")}}</li>
+ <li>{{htmlelement("body")}}</li>
+ <li>{{htmlelement("div")}}</li>
+ <li>{{htmlelement("footer")}}</li>
+ <li>{{htmlelement("h1")}}</li>
+ <li>{{htmlelement("h2")}}</li>
+ <li>{{htmlelement("h3")}}</li>
+ <li>{{htmlelement("h4")}}</li>
+ <li>{{htmlelement("h5")}}</li>
+ <li>{{htmlelement("h6")}}</li>
+ <li>{{htmlelement("header")}}</li>
+ <li>{{htmlelement("main")}}</li>
+ <li>{{htmlelement("nav")}}</li>
+ <li>{{htmlelement("p")}}</li>
+ <li>{{htmlelement("section")}}</li>
+ <li>{{htmlelement("span")}}</li>
+</ul>
+
+<h2 id="语法">语法</h2>
+
+<pre class="syntaxbox">var <var>shadowroot</var> = <var>element</var>.attachShadow(<var>shadowRootInit</var>);
+</pre>
+
+<h3 id="参数">参数</h3>
+
+<dl>
+ <dt><code>shadowRootInit</code></dt>
+ <dd>一个 <code>ShadowRootInit</code> 字典，包括下列字段：
+ <dl>
+  <dt><code>mode 模式</code></dt>
+  <dd>
+  <p>指定 Shadow DOM 树<em>封装模式</em>的字符串，可以是以下值：</p>
+
+  <ul>
+   <li><code>open</code> shadow root元素可以从js外部访问根节点，例如使用 {{domxref("Element.shadowRoot")}}:</li>
+  </ul>
+
+  <pre>element.shadowRoot; // 返回一个ShadowRoot对象</pre>
+
+  <ul>
+   <li><code>closed</code> 拒绝从js外部访问关闭的shadow root节点</li>
+  </ul>
+
+  <pre>element.shadowRoot; // 返回null</pre>
+  </dd>
+  <dt><code>delegatesFocus 焦点委托</code></dt>
+  <dd>一个布尔值, 当设置为 <code>true</code> 时, 指定减轻自定义元素的聚焦性能问题行为.<br>
+  当shadow DOM中不可聚焦的部分被点击时, 让第一个可聚焦的部分成为焦点, 并且shadow host（影子主机）将提供所有可用的 <code>:focus</code> 样式.</dd>
+ </dl>
+ </dd>
+</dl>
+
+<h3 id="返回值">返回值</h3>
+
+<p>返回一个 {{domxref("ShadowRoot")}} 对象或者 <code>null</code>。</p>
+
+<h3 id="异常">异常</h3>
+
+<table class="standard-table">
+ <thead>
+  <tr>
+   <th scope="col">异常</th>
+   <th scope="col">说明</th>
+  </tr>
+ </thead>
+ <tbody>
+  <tr>
+   <td><code>InvalidStateError<br>
+    无效状态错误</code></td>
+   <td>您添加的元素已经是一个shadow host（影子主机）.</td>
+  </tr>
+  <tr>
+   <td>
+    <p><code>NotSupportedError<br>
+     不被支持错误</code></p>
+   </td>
+   <td>您应该添加 HTML 元素的命名空间之外的shadow root, 或者这个元素不能有其他shadow挂载到它上面 (见上).</td>
+  </tr>
+ </tbody>
+</table>
+
+<h2 id="示例">示例</h2>
+
+<p>下面的例子取至 <a href="https://github.com/mdn/web-components-examples/tree/master/word-count-web-component">word-count-web-component</a> 片段( <a href="https://mdn.github.io/web-components-examples/word-count-web-component/">现场看看</a> ). 你可以看到使用 <code>attachShadow()</code> 在代码中间创建一个shadow root, 然后我们可以将自定义元素的内容挂载添加到它上面。</p>
+
+<pre class="brush: js">// 为新元素创建一个类
+class WordCount extends HTMLParagraphElement {
+  constructor() {
+    // 在构造器中先调用一下 super
+    super();
+
+    // 计数器指向元素的父级
+    var wcParent = this.parentNode;
+
+    function countWords(node){
+      var text = node.innerText || node.textContent
+      return text.trim().split(/\s+/g).length;
+    }
+
+    var count = 'Words: ' + countWords(wcParent);
+
+    // 创建一个shadow root
+    var shadow = this.attachShadow({mode: 'open'});
+
+    // 创建文本节点并向其添加计数器
+    var text = document.createElement('span');
+    text.textContent = count;
+
+    // 将其添加到shadow root上
+    shadow.appendChild(text);
+
+    // 当元素内容发生变化时更新计数
+    setInterval(function() {
+      var count = 'Words: ' + countWords(wcParent);
+      text.textContent = count;
+    }, 200);
+  }
+}
+
+// 定义新元素
+customElements.define('word-count', WordCount, { extends: 'p' });</pre>
+
+<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-element-attachshadow', 'attachShadow()')}}</td>
+   <td>{{Spec2('DOM WHATWG')}}</td>
+   <td></td>
+  </tr>
+ </tbody>
+</table>
+
+<h2 id="浏览器兼容性">浏览器兼容性</h2>
+
+
+
+<p>{{Compat("api.Element.attachShadow")}}</p>